IconButton

Icon buttons help people take supplementary actions with a single tap. Follows the Material Design 3 Icon Button specification.

The icon and selectedIcon props accept three forms — a string name (resolved via MaterialCommunityIcons by default), a pre-rendered React element from any icon library, or a render function that receives the resolved { size, color }. See the Icons guide for full details, including how to register a global iconResolver for Lucide, SF Symbols, or custom SVGs.

Usage

Open on Snack ↗

import { IconButton } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { View } from 'react-native'

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
          <IconButton
            icon="heart-outline"
            accessibilityLabel="Favorite"
            onPress={() => {}}
          />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Variants

Variant	Use case
filled	High emphasis, filled container
tonal	Medium emphasis, tonal container
outlined	Medium emphasis, outlined border
standard	Low emphasis, no container

Sizes

Open on Snack ↗

import { IconButton } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { View } from 'react-native'

export default function App() {
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, flexDirection: 'row', alignItems: 'center', justifyContent: 'center', gap: 12 }}>
          <IconButton icon="star" size="small" accessibilityLabel="Star" onPress={() => {}} />
          <IconButton icon="star" size="medium" accessibilityLabel="Star" onPress={() => {}} />
          <IconButton icon="star" size="large" accessibilityLabel="Star" onPress={() => {}} />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Bring your own icon library

import { IconButton } from '@onlynative/components'
import { Heart } from 'lucide-react-native'

<IconButton
  icon={({ size, color }) => <Heart size={size} color={color} />}
  accessibilityLabel="Like"
/>

The render-function form receives the size and color the IconButton would have given to its default icon (24dp for medium, plus the variant + state color), so the icon stays in sync with size/variant changes automatically.

Toggle Mode

Use selected and selectedIcon for toggle behavior:

Open on Snack ↗

import { IconButton } from '@onlynative/components'
import { ThemeProvider } from '@onlynative/core'
import { SafeAreaProvider } from 'react-native-safe-area-context'
import { useState } from 'react'
import { View } from 'react-native'

export default function App() {
  const [liked, setLiked] = useState(false)
  return (
    <SafeAreaProvider>
      <ThemeProvider>
        <View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
          <IconButton
            icon="heart-outline"
            selectedIcon="heart"
            selected={liked}
            onPress={() => setLiked(!liked)}
            accessibilityLabel={liked ? 'Unlike' : 'Like'}
          />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Props

Prop	Type	Default	Required	Description
icon	IconSource	-	Yes	Icon to display. Accepts a string name (resolved via the theme's `iconResolver`, defaulting to `MaterialCommunityIcons`), a pre-rendered element, or a render function that receives `{ size, color }`.
selectedIcon	IconSource	-	No	Icon to display when `selected` is `true` (toggle mode).
iconColor	string	-	No	Overrides the automatic icon color derived from the variant and state.
contentColor	string	-	No	Override the content (icon) color. Takes precedence over `iconColor` when both are provided.
containerColor	string	-	No	Override the container (background) color. State-layer colors (hover, press) are derived automatically.
style	StyleProp<ViewStyle>	-	No	Style applied to the root container. Static form only — the function form `(state) => style` is not supported because the component drives its container background through Reanimated. Use `containerColor` / `contentColor` for state-aware styling.
onPress	() => void	-	No	Called when the button is pressed.
disabled	boolean		No	Disables the button.
variant	enum	filled	No	Visual style variant.
selected	boolean	-	No	Enables toggle mode. The button changes appearance based on selected/unselected state.
size	enum	medium	No	Physical size of the touch target and icon container.
accessibilityLabel	string	-	Yes	Required — icon-only buttons must have a label for screen readers.
onKeyDown	(event: { nativeEvent: { key?: string; }; }) => void	-	No	-