Skip to main content

SelectionMenu

iOS Android
SelectionMenu on iOS SelectionMenu on Android

Native selection menu with modal and embedded modes.

Props​

PropTypeDescription
optionsSelectionMenuOption[]Options to display. See SelectionMenuOption
selectedstring | nullCurrently selected option's data value
disabledbooleanDisables the menu
placeholderstringPlaceholder text when no selection
presentation'modal' | 'embedded'Presentation mode (default: 'modal')
visiblebooleanControls 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) => voidCalled when user selects an option
onRequestClose() => voidCalled when menu is dismissed without selection
android.material'system' | 'm3'Material Design style preference
android.searchablebooleanEmbedded m3 only: typing filters the options. See Searchable dropdown
minFieldHeightnumberEmbedded only: smallest height of the field in points (dp). See Form field
fieldPaddingHorizontalnumberEmbedded 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.densebooleanEmbedded m3 only: the dense, shorter field
testIDstringEmbedded: on the field, which also has the label and takes the touches. Modal: on the component's view. See Testing
accessibilityLabelstringEmbedded: the field's label, with the shown option as its value. Default: the field is labeled by what it shows. See Testing

SelectionMenuOption​

PropertyTypeDescription
labelstringDisplay text
datastringPayload returned by onSelect; what selected matches
disabledbooleanKeeps the option visible but prevents user selection (default: false)
subtitlestringSecondary text under the label. See Icons and subtitles
iconstring | PlatformIconIcon next to the label, the same shapes as Button icons

Modes​

  • Modal mode (default): Menu visibility controlled by visible prop. Use for custom trigger UI.
  • Embedded mode (presentation="embedded"): Native picker UI rendered inline. Menu managed internally.

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 invisible UIButton over the component's frame (showsMenuAsPrimaryAction), which visible opens with UIControl.performPrimaryAction(). A tap outside dismisses it and calls onRequestClose; setting visible back to false closes 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 PopupMenu anchored to the component, with a radio indicator on the selected option.
iOS 26iOS 18Android
The system menu opened from modal mode on iOS 26The system menu opened from modal mode on iOS 18The popup menu with icons on Android

Selected option​

The option matching selected is marked natively when the menu is open:

  • iOS (both modes): a single-selection UIMenu with 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 PopupMenu group 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, or placeholder when selected is null. 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.image and UIAction.subtitle, in both modes (from iOS 17.4 in modal mode).
  • Android modal: the PopupMenu shows 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)
Dropdown rows with icons and subtitles in the M3 exposed dropdown

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 of UITextField'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') and android.dense select the same styles as on TextField: 56dp, or 48dp dense. The placeholder is the field's floating label, as a TextField's label is. 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 26Android
A TextField and a SelectionMenu with the rounded rect, the same size, on iOS 26A Material TextField and an exposed dropdown menu, the same size, on 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: selected stays 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
The M3 exposed dropdown filtered to the states starting with &quot;new&quot;

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);
FieldView with the testIDLabel
iOS (both ios.borderStyles)The menu UIButton, the size of the componentThe shown option or placeholder; with accessibilityLabel, that label and the shown text as its value
Android m3 exposed dropdownThe 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 SpinnerThe SpinnerThe 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.