Looking for documentation on gluestack-ui v2 with NativeWind? Refer to this link.
This is an illustration of a Themed Select component with default configuration.
variant
size
<Select>
  <SelectTrigger variant="outline" size="md">
    <SelectInput placeholder="Select option" />
    <SelectIcon mr="$3">
      <Icon as={ChevronDownIcon} />
    </SelectIcon>
  </SelectTrigger>
  <SelectPortal>
    <SelectBackdrop />
    <SelectContent>
      <SelectDragIndicatorWrapper>
        <SelectDragIndicator />
      </SelectDragIndicatorWrapper>
      <SelectItem label="UX Research" value="ux" />
      <SelectItem label="Web Development" value="web" />
      <SelectItem
        label="Cross Platform Development Process"
        value="cross-platform"
      />
      <SelectItem label="UI Designing" value="ui" isDisabled={true} />
      <SelectItem label="Backend Development" value="backend" />
    </SelectContent>
  </SelectPortal>
</Select>

API Reference

Import

To use this component in your project, include the following import statement in your file.
import { Select } from '@gluestack-ui/themed';

Anatomy

The structure provided below can help you identify and understand a Select component's various parts.
export default () => (
  <Select>
    <SelectTrigger>
      <SelectInput />
      <SelectIcon>
        <Icon />
      </SelectIcon>
    </SelectTrigger>
    <SelectPortal>
      <SelectBackdrop />
      <SelectContent>
        <SelectDragIndicatorWrapper>
          <SelectDragIndicator />
        </SelectDragIndicatorWrapper>
        <SelectItem />
      </SelectContent>
    </SelectPortal>
  </Select>
)

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

Select

Contains all Select related layout style and high-level select props. It inherits all the properties of React Native's View component.
Note: Please note that this select component renders as an Actionsheet on iOS and Android devices for a native feel. On web, it behaves like a regular select element and renders the default HTML options.
Prop
Type
Default
Description
isDisabled
boolean
false
When true, the select is disabled and cannot be edited.
isInvalid
boolean
false
When true, the select displays an error state.
isRequired
boolean
false
When true, sets aria-required="true" on the input.
isHovered
boolean
false
When true, the select displays a hover state.
isFocusVisible
boolean
false
When true, the focus ring of select will be visible.
isFocused
boolean
false
When true, the select displays a focus state.
closeOnOverlayClick
boolean
false
When true, the select will close when the overlay is clicked.
defaultValue
string
-
Sets the initial selected option value for a select component.
initialLabel
string
-
Sets the initial selected Label for a select component.
selectedValue
string
-
Sets the currently selected option value, allowing the component to render with the corresponding option pre-selected.
onValueChange
() => any
-
Callback to be invoked when Select value is changed.
onOpen
() => any
-
Callback to be invoked when Select Dropdown or Actionsheet is opened.
onClose
() => any
-
Callback to be invoked when Select Dropdown or Actionsheet is closed.
Note: Please note that if you want to use the initialLabel prop, you also need to pass the defaultValue or selectedValue prop to select the option value for a select component. Conversely, if you are using the defaultValue prop, you have to utilize the initialLabel prop.

Note: If you want to reset the select component, you should pass 'null' as the value for selectedValue.

SelectTrigger

It inherits all the properties of React Native's Pressable component.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_icon
Prop to style SelectIcon Component
_input
Prop to style SelectInput Component

SelectInput

It inherits all the properties of React Native's TextInput component.

SelectIcon

It inherits all the properties of React Native's Pressable component.

SelectPortal

It is internally mapped wth gluestack-ui's Actionsheet component, which inherits all the properties of React Native's View component.

SelectBackdrop

It is internally mapped wth gluestack-ui's ActionsheetBackdrop component, which is React Native's Pressable component, created using @legendapp/motion's createMotionAnimatedComponent function to add animation to the component. You can use any declarative animation library you prefer.

SelectContent

It is internally mapped wth gluestack-ui's ActionsheetContent component, which inherits all the properties of @legendapp/motion's Motion.View component. With this ActionSheet component, you have the flexibility to use any declarative animation library that suits your needs.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_sectionHeaderBackground
Prop to style SelectActionsheetSectionHeaderText Component

SelectDragIndicatorWrapper

It is internally mapped wth gluestack-ui's ActionsheetDragIndicatorWrapper component, which inherits all the properties of React Native's View component.

SelectDragIndicator

It is internally mapped wth gluestack-ui's ActionsheetDragIndicator component, which inherits all the properties of React Native's View component.

SelectItem

It internally uses gluestack-ui's ActionsheetItem and Actionsheet.ItemText component, which inherits all the properties of React Native's Pressable component.
Prop
Type
Default
Description
isDisabled
bool
false
When true, its disabled state activates.
label
string
-
setting label that displays to the user.
value
string
-
The value to be used for the item. This is the value that will be returned on form submission.
Descendants Styling Props Props to style child components.
Sx Prop
Description
_text
Prop to style SelectItemText Component

SelectScrollView

It is internally mapped wth gluestack-ui's Actionsheet.ScrollView component, which inherits all the properties of React Native's ScrollView component.

SelectVirtualizedList

It is internally mapped wth gluestack-ui's Actionsheet.VirtualizedList component, which inherits all the properties of React Native's VirtualizedList component.

SelectFlatList

It is internally mapped wth gluestack-ui's Actionsheet.FlatList component, which inherits all the properties of React Native's FlatList component.

SelectSectionList

It is internally mapped wth gluestack-ui's Actionsheet.SectionList component, which inherits all the properties of React Native's SectionList component.

SelectSectionHeaderText

It is internally mapped wth gluestack-ui's Actionsheet.SectionHeaderText component, which inherits all the properties of React Native's Text component.

Features

  • Support for native and web platforms separately.
  • Support for passing custom trigger.

Accessibility

We have outlined the various features that ensure the Select component is accessible to all users, including those with disabilities.These features help ensure that your application is inclusive and meets accessibility standards.Adheres to the WAI-ARIA design pattern.

Keyboard

  • Tab + Space: Triggers the select's action.

Screen Reader

  • VoiceOver: When the select is focused, the screen reader will announce the select content.

Themed

The themed version of the component is a pre-styled version of the component, which allows you to quickly integrate the component into your project. The component's design and functionality are fully defined, allowing you to focus on the more important aspects of your project. To know more about Themed Library please visit this link.

Props

Select component is created using View component from react-native. It extends all the props supported by React Native View, utility props and the props mentioned below.

Select

Name
Value
Default
size
xl | lg | md | sm
md
variant
underlined | outline | rounded
outline
Note: These props are exclusively applicable when utilizing the default configuration of gluestack-ui/config. If you are using a custom theme, these props may not be available.

Examples

The Examples section provides visual representations of the different variants of the component, allowing you to quickly and easily determine which one best fits your needs. Simply copy the code and integrate it into your project.

Select FormControlled

The Select component with FormControl example demonstrates how to manage its state using the FormControl component. This allows for easy integration with forms and form validation.
<FormControl isRequired isInvalid>
  <FormControlLabel>
    <FormControlLabelText>Choose your favorite color</FormControlLabelText>
  </FormControlLabel>
  <Select>
    <SelectTrigger>
      <SelectInput placeholder="Select option" />
      <SelectIcon mr="$3">
        <Icon as={ChevronDownIcon} />
      </SelectIcon>
    </SelectTrigger>
    <SelectPortal>
      <SelectBackdrop />
      <SelectContent>
        <SelectDragIndicatorWrapper>
          <SelectDragIndicator />
        </SelectDragIndicatorWrapper>
        <SelectItem label="Red" value="red" />
        <SelectItem label="Blue" value="blue" />
        <SelectItem label="Black" value="black" />
        <SelectItem label="Pink" value="pink" isDisabled={true} />
        <SelectItem label="Green" value="green" />
      </SelectContent>
    </SelectPortal>
  </Select>
  <FormControlHelper>
    <FormControlHelperText>
      You can only select one option
    </FormControlHelperText>
  </FormControlHelper>
  <FormControlError>
    <FormControlErrorIcon as={AlertCircleIcon} />
    <FormControlErrorText>Mandatory field</FormControlErrorText>
  </FormControlError>
</FormControl>

Unstyled

All the components in gluestack-ui are unstyled by default. To customize your UI using the extendedTheme, please refer to this link. The import names of components serve as keys to customize each component.

Spec Doc

Explore the comprehensive details of the Select in this document, including its implementation details, checklist, and potential future additions. Dive into the thought process behind the component and gain insights into its development journey.