Skip to main content

Button

iOS Android
Button on iOS Button on Android

Native button using MaterialButton with the Material 3 Expressive styles on Android and UIButton with a UIButton.Configuration on iOS. Each platform draws its own button: Android gets the Expressive shapes, sizes and press morph, iOS gets the system button of the iOS version it runs on.

import { Button } from 'react-native-platform-components';

<Button label="Save" onPress={save} />
<Button label="Cancel" variant="text" onPress={cancel} />
<Button icon="plus" variant="tonal" accessibilityLabel="Add" onPress={add} />

Props​

PropTypeDescription
labelstringButton text. Omit for an icon-only button
iconPlatformIconIcon next to the label, or alone. See Icons
iconPosition'leading' | 'trailing' | 'top' | 'bottom'Where the icon sits relative to the label. See Icon placement. Default: 'leading'
variant'filled' | 'tonal' | 'outlined' | 'text' | 'elevated' | 'glass' | 'prominentGlass' | 'clearGlass' | 'prominentClearGlass'Emphasis. See Variants. Default: 'filled'
size'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'Size. See Sizes. Default: 'small'
shape'round' | 'square'Corner shape. See Shape. Default: platform default
cornerRadiusnumberCorner radius in points (dp). Overrides shape. See Shape
disabledbooleanDisables the button
loadingbooleanShows a spinner in place of the label and icon and ignores presses. See Loading
colorColorValueContainer (background) color
tintColorColorValueLabel and icon color
disabledColorColorValueContainer color while disabled. Unset keeps the platform's disabled look
disabledTintColorColorValueLabel and icon color while disabled. Unset keeps the platform's disabled look
labelStyle{ fontFamily?, fontSize?, fontWeight?, fontStyle? }Label font. See Styling
maxFontSizeMultipliernumberCap on the label's text-size scaling, as on Text. 0 / unset = no cap. See Styling
accessibilityLabelstringScreen-reader label. Defaults to label; give icon-only buttons one
haptics'selection' | 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'none'Haptic played on a press (a toggle's included) and on a menu pick, not when a menu opens or while loading or disabled. See Haptics. Default: none
onPress() => voidCalled when the button is pressed. A button with a menu opens the menu instead
selectedbooleanMakes the button a toggle, with this as its controlled state. See Toggle
onSelectedChange(selected: boolean) => voidCalled when a toggle is pressed, with the state it asks for
menuContextMenuAction[]A menu the button opens when pressed. See Menu
onMenuSelect(id: string, title: string) => voidCalled when a menu item is picked
onMenuOpen() => voidCalled when the menu opens
onMenuClose() => voidCalled when the menu closes
testIDstringTest ID of the native button, which also has the label and takes the touches. See Testing

iOS Props (ios)​

PropTypeDescription
symbolEffect'bounce' | 'pulse' | 'variableColor' | 'wiggle' | 'rotate' | 'breathe'Animates the SF Symbol icon. See Symbol effects
symbolEffectTriggernumber | stringPlays symbolEffect once each time it changes. Unset, the effect repeats

Android Props (android)​

PropTypeDescription
rippleColorColorValueRipple shown while pressing
strokeColorColorValueOutline color (outlined variant)
material'm3' | 'expressive'Material style: Material 3 Expressive (default) or the classic Material 3 button. See Material style

Variants​

Five levels of emphasis, from highest to lowest. Android uses the Material 3 Expressive button styles; iOS uses the closest UIButton.Configuration, so buttons look like every other button on that iOS version.

VariantAndroidiOS
filledFilled button (materialButtonStyle).filled()
tonalFilled tonal button (materialButtonTonalStyle).tinted()
outlinedOutlined button (materialButtonOutlinedStyle).bordered()
textText button (borderlessButtonStyle).plain()
elevatedElevated button (materialButtonElevatedStyle).gray()

Liquid Glass​

Four more variants give the iOS 26 Liquid Glass buttons. Earlier iOS versions and Android fall back to the closest regular style, so the same code works everywhere.

VariantiOS 26+Before iOS 26Android
glass.glass().gray()Tonal
prominentGlass.prominentGlass().filled()Filled
clearGlass.clearGlass().gray()Tonal
prominentClearGlass.prominentClearGlass().filled()Filled

color tints the prominent glass (baseBackgroundColor) and tintColor colors the label and icon, as for filled. Pressed and disabled states follow the system glass behavior. In a ButtonGroup, selected glass buttons (clear or not) use the prominent glass style.

Clear glass is the more transparent Liquid Glass, for buttons over photos, maps and video, where the regular glass would hide too much of the content. UIKit draws prominentClearGlass untinted unless you give it a color.

<Button label="Done" variant="prominentGlass" color="#0A84FF" tintColor="white" />
<Button icon="xmark" variant="glass" accessibilityLabel="Close" />
<Button icon="square.and.arrow.up" variant="clearGlass" accessibilityLabel="Share" />
Clear glass (top) and regular glass (bottom) over a photo, iOS 26
Clear glass buttons above regular glass buttons over a photo on iOS 26

Sizes​

Material 3 Expressive defines five button sizes; iOS maps them onto UIButton.Configuration.Size.

SizeAndroid heightiOS
xsmall32dp.mini
small40dp (default).small
medium56dp.medium
large96dp.large
xlarge136dp.large

The button wraps its content. Give it alignSelf: 'stretch' or a width style to make it fill.

Shape​

Material 3 Expressive buttons come in two shapes: round (a pill, the default) and square (rounded corners). On Android the shape morphs when pressed, the signature Expressive interaction, and selected buttons in a ButtonGroup morph too. On iOS round sets the capsule corner style and square the large one; unset keeps UIKit's dynamic corners.

<Button label="Round" shape="round" size="medium" />
<Button label="Square" shape="square" size="medium" />

When a design specifies a radius, set cornerRadius (points on iOS, dp on Android). It overrides shape: iOS uses the fixed corner style with background.cornerRadius, Android sets the corner size on the button's shapeAppearanceModel, which turns off the Expressive press morph.

<Button label="Radius 6" cornerRadius={6} />

Loading​

loading swaps the label and icon for the platform's spinner while a request is in flight. The button keeps its size, so the layout doesn't jump, keeps its enabled colors, and ignores presses. It also sets accessibilityState.busy, merged with any accessibilityState you pass.

<Button label="Save" loading={saving} onPress={save} />
PlatformSpinner
iOSUIButton.Configuration.showsActivityIndicator, centred in the button's idle size
AndroidA Material circular progress indicator (IndeterminateDrawable) at the icon size, drawn as the button icon in the label color; the label is hidden and the width kept

Icons​

icon accepts the same shapes as SegmentedControl: an SF Symbol or drawable name, an image asset, or an { ios, android, web } set (the web draws images only; see Icons).

// Native symbol on each platform
<Button
label="Share"
icon={{
ios: { type: 'sfSymbol', name: 'square.and.arrow.up' },
android: { type: 'drawable', name: 'share' },
}}
/>

// One image asset for both, drawn as a tinted template
<Button label="Alerts" icon={{ type: 'image', source: require('./bell.png') }} />

The icon sits before the label by default. iconPosition="trailing" puts it after the label (iOS imagePlacement = .trailing, Android iconGravity = textEnd):

<Button label="Next" icon="chevron.right" iconPosition="trailing" />

Icon placement​

iconPosition="top" and "bottom" stack the icon above or below the label, and the button measures itself taller to fit both.

iconPositioniOS (imagePlacement)Android (iconGravity)
leading.leadingstart
trailing.trailingtextEnd
top.toptextTop
bottom.bottomtextTop: Material has no bottom gravity, so the icon goes on top
<Button label="Share" icon="square.and.arrow.up" iconPosition="top" variant="tonal" />
iOS 26Android
Buttons with the icon above and below the label on iOS 26Buttons with the icon above the label on Android

A button with an icon and no label is an icon button: on Android it uses the Material 3 Expressive icon button styles (a square container that keeps the variant), on iOS an image-only UIButton. Always give it an accessibilityLabel.

Toggle​

selected makes the button a toggle, like Bold in a text editor or a favorite star. It is controlled: a press calls onSelectedChange with the opposite of selected, and the button shows the new state once selected changes. A press the parent doesn't take goes back, as React Native's Switch does. onPress is still called on every press.

const [bold, setBold] = useState(false);

<Button label="Bold" selected={bold} onSelectedChange={setBold} />
PlatformToggle
iOSchangesSelectionAsPrimaryAction and isSelected, with UIKit's selected look for the configuration: tonal becomes filled, and outlined, text, elevated and glass become tinted. UIKit has no selected look for filled, prominentGlass and the clear glass variants, so while off those show .gray(), .glass() and .clearGlass(), and selected clear glass takes .prominentGlass(). VoiceOver reads the selected state.
AndroidA checkable MaterialButton (isCheckable, isChecked): the Material 3 toggle button colors, and the Expressive shape morph between the round and square shapes. TalkBack reads the checked state.
iOS 26Android
Toggle buttons on and off on iOS 26Toggle buttons on and off on Android

menu gives the button a menu that opens when it is pressed, in place of onPress, with the same items as ContextMenu: sections, submenus, icons, checkmarks and destructive actions. onMenuSelect reports the picked item's id and title.

<Button
label="Sort"
icon="arrow.up.arrow.down"
variant="tonal"
menu={[
{
id: 'sort-by',
title: 'Sort by',
displayInline: true,
subactions: [
{ id: 'name', title: 'Name', state: sortBy === 'name' ? 'on' : 'off' },
{ id: 'date', title: 'Date', state: sortBy === 'date' ? 'on' : 'off' },
],
},
{ id: 'reset', title: 'Reset', attributes: { destructive: true } },
]}
onMenuSelect={(id) => setSortBy(id)}
/>
PlatformMenu
iOSUIButton.menu with showsMenuAsPrimaryAction, so the system menu opens from the button on touch down. keepsMenuPresented actions update the open menu in place
AndroidA PopupMenu anchored to the button, with icons shown. It closes on every pick, as Android menus do

A button with a menu isn't a toggle: a press opens the menu, so leave selected unset. The menu stays closed while the button is disabled or loading.

An item's testID lands on its menu row, so end-to-end tests can tap it by ID (Detox by.id). See Testing menu actions.

iOS 26Android
The button&#39;s menu open on iOS 26The button&#39;s popup menu open on Android

Symbol effects (iOS)​

ios.symbolEffect animates an SF Symbol icon with UIImageView.addSymbolEffect. Without ios.symbolEffectTrigger the effect repeats until you unset it, for a state such as syncing or recording. With a trigger, it plays once each time the trigger changes (the first value doesn't play), for feedback on an event:

// Repeats while syncing
<Button label="Syncing" icon="arrow.triangle.2.circlepath" ios={{ symbolEffect: syncing ? 'rotate' : undefined }} />

// Bounces once per new message
<Button icon="bell" accessibilityLabel="Inbox" ios={{ symbolEffect: 'bounce', symbolEffectTrigger: unread }} />
EffectiOSRepeatingOnce
bounce17+18+ (repeated bounce on 17)✓
pulse17+✓✓
variableColor17+✓✓
wiggle18+✓✓
rotate18+✓✓
breathe18+✓✓

Effects the running iOS doesn't have do nothing, and so do image icons (only SF Symbols animate). A repeating effect stops while loading. Android has no symbol effects; the prop is ignored there.

Styling​

Colors take any React Native ColorValue. Fonts follow the Text style conventions.

<Button
label="Brand"
color="#FF6B35"
tintColor="white"
labelStyle={{ fontWeight: '700', fontSize: 15 }}
android={{ rippleColor: 'rgba(255, 255, 255, 0.3)' }}
/>
PropAndroidiOS
colorbackgroundTintbaseBackgroundColor
tintColorText color and iconTintbaseForegroundColor
disabledColorDisabled state of backgroundTintBackground color while !isEnabled (configurationUpdateHandler)
disabledTintColorDisabled state of the text color and iconTintTitle and image color while !isEnabled
labelStyleTypeface and sizeTitle font
maxFontSizeMultiplierScaled sp size capped at the multiplierDynamic Type size capped at the multiplier
android.rippleColorPress ripple—
android.strokeColorOutline (outlined variant)—

The label grows with the system text size (Dynamic Type on iOS, font scale on Android). maxFontSizeMultiplier caps that growth with the Text semantics: 2 lets the label reach twice its default size and no more; unset or 0 means no cap. On iOS the cap applies to the system title font and to a labelStyle without a fontSize (which follows the body text style); a fixed labelStyle.fontSize doesn't scale on iOS, so there is nothing to cap.

<Button label="Continue" maxFontSizeMultiplier={1.5} />

A disabled button keeps the platform's disabled look (Material's disabled colors on Android, UIKit's on iOS) unless you set disabledColor / disabledTintColor, for example to keep the brand color at reduced opacity:

<Button
label="Brand"
color="#FF6B35"
tintColor="white"
disabledColor="rgba(255, 107, 53, 0.4)"
disabledTintColor="rgba(255, 255, 255, 0.8)"
disabled
/>

Without these props the button takes its colors from the theme: the app's Material 3 theme or the brand color set with useNativeTheme on Android, the tint color on iOS.

Inside a FloatingToolbar​

Buttons placed in a FloatingToolbar pick up the toolbar's button styles on Android, as Material's own toolbar children do: filled and text buttons become the toolbar's flat buttons, icon-only text buttons become the toolbar's icon buttons, and tonal keeps its container for an emphasized action.

Material style​

android.material picks the Android design generation: 'expressive' (default) gives the Material 3 Expressive styles with their five sizes, two shapes and press morph; 'm3' gives the classic Material 3 button, which has one size and shape, so size and shape are ignored. Use 'm3' on screens that keep the older Material 3 look. Buttons inside a FloatingToolbar always take the toolbar's Expressive styles. SegmentedControl and ButtonGroup take the same prop.

Testing​

testID is on the native button (UIButton, MaterialButton), the view that also has the label (accessibilityLabel, else label) and takes the touches. An end-to-end test can find the button by ID, read its label, even as it changes, and tap it:

// Detox
await waitFor(element(by.id('statement-submit')))
.toHaveLabel('Parse Statement')
.withTimeout(10000);
await element(by.id('statement-submit')).tap();

See Test IDs in end-to-end tests. The Jest mock renders a Pressable with the button role.

Android theme​

The Expressive look is a set of widget styles applied over your app theme, so your colors (and useNativeTheme) are kept. It works with a Theme.Material3 app theme and with the library's Material 3 fallback; see Android Theme Configuration.