SelectionMenu
| iOS | Android |
![]() |
![]() |
Native selection menu with modal and embedded modes.
Props
| Prop | Type | Description |
|---|---|---|
options | SelectionMenuOption[] | Options to display. See SelectionMenuOption |
selected | string | null | Currently selected option's data value |
disabled | boolean | Disables the menu |
placeholder | string | Placeholder text when no selection |
presentation | 'modal' | 'embedded' | Presentation mode (default: 'modal') |
visible | boolean | Controls modal mode menu visibility |
haptics | 'selection' | 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error' | 'none' | Haptic played when the user picks an option. See Haptics. Default: none |
onSelect | (data, label, index) => void | Called when user selects an option |
onRequestClose | () => void | Called when menu is dismissed without selection |
android.material | 'system' | 'm3' | Material Design style preference |
android.searchable | boolean | Embedded m3 only: typing filters the options. See Searchable dropdown |
minFieldHeight | number | Embedded only: smallest height of the field in points (dp). See Form field |
fieldPaddingHorizontal | number | Embedded only: space between the field's sides and its text in points (dp). See Form field |
ios.borderStyle | 'none' | 'roundedRect' | Embedded only: a borderless pop-up button (default) or a field box. See Form field |
android.variant | 'outlined' | 'filled' | Embedded m3 only: the Material exposed dropdown style (default: 'outlined') |
android.dense | boolean | Embedded m3 only: the dense, shorter field |
testID | string | Embedded: on the field, which also has the label and takes the touches. Modal: on the component's view. See Testing |
accessibilityLabel | string | Embedded: the field's label, with the shown option as its value. Default: the field is labeled by what it shows. See Testing |
SelectionMenuOption
| Property | Type | Description |
|---|---|---|
label | string | Display text |
data | string | Payload returned by onSelect; what selected matches |
disabled | boolean | Keeps the option visible but prevents user selection (default: false) |
subtitle | string | Secondary text under the label. See Icons and subtitles |
icon | string | PlatformIcon | Icon next to the label, the same shapes as Button icons |
Modes
- Modal mode (default): Menu visibility controlled by
visibleprop. Use for custom trigger UI. - Embedded mode (
presentation="embedded"): Native picker UI rendered inline. Menu managed internally.
Modal mode
In modal mode the component is invisible and takes no touches; it only marks where the menu opens. Place it next to your own trigger, set visible to open the menu, and close it again from onSelect and onRequestClose:
const [open, setOpen] = useState(false);
<Pressable onPress={() => setOpen(true)}>
<Text>{selected ?? 'Pick a state'}</Text>
</Pressable>
<SelectionMenu
options={STATES}
selected={selected}
visible={open}
onSelect={(data) => {
setSelected(data);
setOpen(false);
}}
onRequestClose={() => setOpen(false)}
/>
- iOS 17.4+: a real system
UIMenu, with the system look (Liquid Glass on iOS 26), scrolling and the checkmark on the selected option. It hangs off an invisibleUIButtonover the component's frame (showsMenuAsPrimaryAction), whichvisibleopens withUIControl.performPrimaryAction(). A tap outside dismisses it and callsonRequestClose; settingvisibleback tofalsecloses it without a callback. On iOS 26 that dismissing tap also reaches the view underneath. - iOS 15.1 to 17.3: UIKit has no public way to open a menu without a touch, so modal mode falls back to a popover styled like a system menu (a blurred material panel), with the checkmark on the selected row. It shows labels only: no icons or subtitles.
- Android: a
PopupMenuanchored to the component, with a radio indicator on the selected option.
| iOS 26 | iOS 18 | Android |
|---|---|---|
![]() |
Selected option
The option matching selected is marked natively when the menu is open:
- iOS (both modes): a single-selection
UIMenuwith the system checkmark on the selected action. Before iOS 17.4, modal mode's popover draws the checkmark in the leading position like a system menu. - Android modal: a single-choice
PopupMenugroup with the selected item checked (radio indicator). - Android embedded,
m3: the exposed dropdown highlights the selected item. - Android embedded,
system: the Spinner shows the selected label, orplaceholderwhenselectedisnull. The placeholder is not a selectable option.
Selection stays controlled: the mark follows the selected prop, not the last tap.
Use a unique, non-empty data string for each option. Native controls reserve
the empty string for no selection; use selected={null} to clear the choice.
Development builds warn about empty or duplicate identifiers without logging
their contents.
Set disabled: true on an option to show an unavailable choice. It remains in
the list and keeps its original callback index; the Android searchable dropdown
also preserves its disabled state while filtering. The parent can still select
a disabled option programmatically through selected. Reopen an already open
native menu after changing its options to refresh the visible menu snapshot.
<SelectionMenu
presentation="embedded"
selected={plan}
onSelect={setPlan}
options={[
{ label: 'Basic', data: 'basic' },
{ label: 'Team — currently unavailable', data: 'team', disabled: true },
{ label: 'Enterprise', data: 'enterprise' },
]}
/>
Icons and subtitles
Each option can carry an icon and a subtitle:
const OPTIONS = [
{
label: 'Push',
data: 'push',
subtitle: 'On this device',
icon: { type: 'image', source: require('./bell.png') },
},
{
label: 'Email',
data: 'email',
subtitle: 'A daily digest',
icon: { ios: 'envelope', android: 'send' },
},
{
label: 'Off',
data: 'off',
subtitle: 'No notifications',
icon: { ios: 'bell.slash', android: 'remove_circle' },
},
];
- iOS:
UIAction.imageandUIAction.subtitle, in both modes (from iOS 17.4 in modal mode). - Android modal: the
PopupMenushows the icons (setForceShowIcon). Its rows have a single line, so subtitles aren't shown there. - Android embedded,
m3: the exposed dropdown's rows get a leading icon and a second line, laid out like Material list items. The closed field shows the label. - Android embedded,
system: labels only. The platform Spinner sizes its list to the widest row and anchors it at the field's start, so rich rows would run off the edge of the screen.
Image sources are drawn as templates in the menu's icon color unless tinted: false; on Android they sit in the 24dp icon box, scaled down if larger.
Android embedded (m3) |
|---|
Form field
In a form, the embedded menu can take the same size as a TextField beside it.
- iOS:
ios.borderStyle: 'roundedRect'draws the field box, a copy ofUITextField's rounded rect (34pt, a hairline border, 7pt of padding). The selected option shows in the label color, the placeholder in the placeholder color, and a chevron sits at the trailing edge. The default,'none', is the borderless pop-up button in the tint color, 44pt tall. - Android:
android.material: 'm3'is the Material 3 exposed dropdown menu.android.variant('outlined'or'filled') andandroid.denseselect the same styles as on TextField: 56dp, or 48dp dense. Theplaceholderis the field's floating label, as a TextField'slabelis. The default'system'Spinner is as tall as Material's 48dp touch target.
minFieldHeight and fieldPaddingHorizontal work as they do on TextField. minFieldHeight is the smallest height of the field: the extra space goes above and below the text, which stays centered, and Material's resting label stays level with it. fieldPaddingHorizontal is the space between the field's leading side and its text; the trailing side keeps room for the arrow or chevron. A style height taller than the field centers it on Android; on iOS the box takes the full height.
<TextField label="City" value={city} onChangeText={setCity} />
<SelectionMenu
presentation="embedded"
options={STATES}
selected={state}
placeholder="State"
onSelect={setState}
ios={{ borderStyle: 'roundedRect' }}
android={{ material: 'm3' }}
/>
| iOS 26 | Android |
|---|---|
Searchable dropdown (Android)
With presentation="embedded", android.material="m3" and android.searchable, the exposed dropdown's field takes typing and filters the options as the user types: an option matches when its label, or one of its words, starts with the text (case-insensitive, as Android's ArrayAdapter filters).
<SelectionMenu
presentation="embedded"
options={STATES}
selected={selected}
placeholder="State"
android={{ material: 'm3', searchable: true }}
onSelect={(data) => setSelected(data)}
/>
- Tapping the field selects its text, so typing replaces it, and opens the full list.
- Picking an option calls
onSelect. The text is only a query:selectedstays the source of truth. - When the field loses focus (the keyboard's Done key, a tap outside the open list, or a pick), the query goes and the field shows the selected option's label again, or the placeholder when nothing is selected. Text that matches nothing never becomes a selection.
searchable is ignored in modal mode, by the system Spinner and on iOS, where menus aren't searchable.
| Android |
|---|
![]() |
Testing
In embedded mode, testID is on the field: the native view that shows the selected option (or the placeholder), has the accessibility label and opens the menu when tapped. An end-to-end test can find it by ID, read its label as the selection changes and tap it:
// Detox
await waitFor(element(by.id('state-menu')))
.toHaveLabel('Select a state')
.withTimeout(6000);
await element(by.id('state-menu')).tap();
await element(by.text('Arizona')).atIndex(0).tap();
await waitFor(element(by.id('state-menu')))
.toHaveLabel('Arizona')
.withTimeout(6000);
| Field | View with the testID | Label |
|---|---|---|
iOS (both ios.borderStyles) | The menu UIButton, the size of the component | The shown option or placeholder; with accessibilityLabel, that label and the shown text as its value |
Android m3 exposed dropdown | The dropdown's text field (an EditText) | With accessibilityLabel, that label (its content description) and the selected option as its state description. Without one, TalkBack reads the text with the placeholder (Material's floating label), and Detox's toHaveLabel finds no label: check the value with toHaveText |
Android system Spinner | The Spinner | The shown option or placeholder; with accessibilityLabel, that label and the shown option as its state description |
The host view React Native creates carries neither the ID nor the label, so VoiceOver and TalkBack announce the field once. In modal mode the component has no field of its own: testID and accessibilityLabel stay on its invisible view, and your trigger carries its own.
Up to 1.9.0, the embedded testID was on the component's container. Tests that reached the field through it, such as element(by.type('android.widget.EditText').withAncestor(by.id('state-menu'))), find it with element(by.id('state-menu')) now.
See Test IDs in end-to-end tests. The Jest mock renders the embedded field as a view with the button role, carrying testID and the same label.



