IconButton

An icon-only pressable that shares variant and size logic with Button. Because there is no visible text label, accessibilityLabel is required by the type system — screen readers need it to announce the button’s purpose.

When to use: Toolbar actions, navigation actions (back, close, search), row-level actions (edit, delete, share) where space is too tight for a text label.

When not to use: When a text label fits — a labeled Button is always clearer than an IconButton. When you need a standalone decorative icon — use Icon.

Import

import { IconButton } from '@/components';
import { ArrowLeft, X, MagnifyingGlass } from 'phosphor-react-native';

Usage

<IconButton
  icon={ArrowLeft}
  accessibilityLabel="Go back"
  variant="ghost"
  onPress={router.back}
/>

Props

Prop	Type	Default	Description
`icon`	`PhosphorIconComponent`	—	Icon to display (required)
`accessibilityLabel`	`string`	—	Screen reader label (required)
`variant`	`'primary' \| 'secondary' \| 'ghost' \| 'destructive'`	`'ghost'`	Visual style
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	Hit target and icon size
`shape`	`'default' \| 'pill'`	`theme.buttonShape`	Border radius
`isElevated`	`boolean`	`false`	Adds shadow
`isDisabled`	`boolean`	`false`	Reduces opacity; blocks interaction
`onPress`	`() => void`	—	Press handler
`testID`	`string`	—	For testing

Common patterns

// Navigation bar back button
<IconButton icon={ArrowLeft} accessibilityLabel="Go back" variant="ghost" onPress={router.back} />

// Navigation bar action (right side)
<IconButton icon={MagnifyingGlass} accessibilityLabel="Search" variant="ghost" onPress={openSearch} />

// Modal close button
<IconButton icon={X} accessibilityLabel="Close" variant="ghost" size="md" onPress={close} />

// Destructive row action
<IconButton icon={Trash} accessibilityLabel="Delete item" variant="destructive" size="sm" onPress={del} />

Do / Don’t

Do: Always provide accessibilityLabel — it is required.

<IconButton icon={Bell} accessibilityLabel="Notifications" onPress={openNotifs} />

Don’t: Use an IconButton for a decorative icon. Use Icon instead.

// ✗ No press handler, shouldn't be a button
<IconButton icon={CheckCircle} accessibilityLabel="Completed" />
// ✓
<Icon icon={CheckCircle} size="md" color="success" />

Don’t: Use more than 2 IconButtons in a navigation bar right slot.

Button — text-labeled button
Icon — non-interactive icon
TopNavBar — passes rightActions as IconButton props