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 '@rootnative/components'
import { ThemeProvider } from '@rootnative/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

Five MD3 Expressive sizes. s is the default.

size	Height	Icon
xs	32dp	20dp
s	40dp	24dp
m	56dp	24dp
l	96dp	32dp
xl	136dp	40dp

Open on Snack ↗

import { IconButton } from '@rootnative/components'
import { ThemeProvider } from '@rootnative/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="xs" accessibilityLabel="Star" onPress={() => {}} />
          <IconButton icon="star" size="s" accessibilityLabel="Star" onPress={() => {}} />
          <IconButton icon="star" size="m" accessibilityLabel="Star" onPress={() => {}} />
        </View>
      </ThemeProvider>
    </SafeAreaProvider>
  )
}

Width and shape

width trades horizontal padding at a fixed height — 'narrow', 'uniform' (default), or 'wide'. At size="s" that is 32 / 40 / 52dp wide.

shape controls the resting container: 'round' (default) rests as a circle/pill, 'square' rests at a size-dependent corner. Toggle buttons invert their shape when selected, so a round toggle squares off to signal the change.

<IconButton icon="star" width="wide" accessibilityLabel="Star" />
<IconButton icon="star" shape="square" accessibilityLabel="Star" />

Bring your own icon library

import { IconButton } from '@rootnative/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 at the default s size, 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 '@rootnative/components'
import { ThemeProvider } from '@rootnative/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	s	No	MD3 Expressive size — one of `'xs' | 's' | 'm' | 'l' | 'xl'`. Sets container height and icon size.
width	enum	uniform	No	Width variant. `'uniform'` is a square container; `'narrow'`/`'wide'` adjust horizontal padding around the icon.
shape	enum	round	No	Container shape. `'round'` is a pill/circle; `'square'` rests at a size-dependent corner. Toggle buttons invert the shape when selected.
accessibilityLabel	string	-	Yes	Required — icon-only buttons must have a label for screen readers.
onKeyDown	(event: { nativeEvent: { key?: string; }; }) => void	-	No	-