Select

Present options conveniently in a collapsible view, allowing users to expand and select items from a dropdown list.

Installation

API Reference

Important Note

This is the documentation for gluestack-ui v2 (beta). For @gluestack-ui/themed (stable) documentation, refer to gluestack-ui v1.

This is an illustration of Select component.

variant

size

<Select>
  <SelectTrigger variant="outline" size="md">
    <SelectInput placeholder="Select option" />
    <SelectIcon className="mr-3" as={ChevronDownIcon} />
  </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 Development Process"
      />
      <SelectItem label="UI Designing" value="ui" isDisabled={true} />
      <SelectItem label="Backend Development" value="backend" />
    </SelectContent>
  </SelectPortal>
</Select>

Installation

CLI

Manual

Run the following command:

npx gluestack-ui add select

Step 1: Install the following dependencies:

npm i @gluestack-ui/select

Step 2: Copy and paste the following code into your project.

import React, { useMemo } from "react"
import { tva } from "@gluestack-ui/nativewind-utils/tva"
import { Svg } from "react-native-svg"
import { withStyleContextAndStates } from "@gluestack-ui/nativewind-utils/withStyleContextAndStates"
import {
  withStyleContext,
  useStyleContext,
} from "@gluestack-ui/nativewind-utils/withStyleContext"
import type { VariantProps } from "@gluestack-ui/nativewind-utils"
import { createSelect } from "@gluestack-ui/select"
import { cssInterop } from "nativewind"
import {
  Actionsheet,
  ActionsheetContent,
  ActionsheetItem,
  ActionsheetItemText,
  ActionsheetDragIndicator,
  ActionsheetDragIndicatorWrapper,
  ActionsheetBackdrop,
  ActionsheetScrollView,
  ActionsheetVirtualizedList,
  ActionsheetFlatList,
  ActionsheetSectionList,
  ActionsheetSectionHeaderText,
} from "./select-actionsheet"
import { Pressable, View, TextInput, Platform } from "react-native"

const SelectTriggerWrapper = React.forwardRef<
  React.ElementRef<typeof Pressable>,
  React.ComponentProps<typeof Pressable>
>(({ ...props }, ref) => {
  return <Pressable {...props} ref={ref} />
})

const selectIconStyle = tva({
  base: "text-background-500 fill-none",
  parentVariants: {
    size: {
      "2xs": "h-3 w-3",
      xs: "h-3.5 w-3.5",
      sm: "h-4 w-4",
      md: "h-[18px] w-[18px]",
      lg: "h-5 w-5",
      xl: "h-6 w-6",
    },
  },
})

const selectStyle = tva({
  base: "",
})

const selectTriggerStyle = tva({
  base: "border border-background-300 rounded flex-row items-center overflow-hidden data-[hover=true]:border-outline-400 data-[focus=true]:border-primary-700 data-[disabled=true]:opacity-40 data-[disabled=true]:data-[hover=true]:border-background-300",
  variants: {
    size: {
      xl: "h-12",
      lg: "h-11",
      md: "h-10",
      sm: "h-9",
    },
    variant: {
      underlined:
        "border-0 border-b rounded-none data-[hover=true]:border-primary-700 data-[focus=true]:border-primary-700 data-[focus=true]:web:shadow-[inset_0_-1px_0_0] data-[focus=true]:web:shadow-primary-700 data-[invalid=true]:border-error-700 data-[invalid=true]:web:shadow-error-700",
      outline:
        "data-[focus=true]:border-primary-700 data-[focus=true]:web:shadow-[inset_0_0_0_1px] data-[focus=true]:data-[hover=true]:web:shadow-primary-600 data-[invalid=true]:web:shadow-[inset_0_0_0_1px] data-[invalid=true]:border-error-700 data-[invalid=true]:web:shadow-error-700 data-[invalid=true]:data-[hover=true]:border-error-700",
      rounded:
        "rounded-full data-[focus=true]:border-primary-700 data-[focus=true]:web:shadow-[inset_0_0_0_1px] data-[focus=true]:web:shadow-primary-700 data-[invalid=true]:border-error-700 data-[invalid=true]:web:shadow-error-700",
    },
  },
})

const selectInputStyle = tva({
  base: "py-auto px-3 placeholder:text-typography-500 web:w-full h-full text-typography-900 pointer-events-none web:outline-none ios:leading-[0px]",
  parentVariants: {
    size: {
      xl: "text-xl",
      lg: "text-lg",
      md: "text-base",
      sm: "text-sm",
    },
    variant: {
      underlined: "px-0",
      outline: "",
      rounded: "px-4",
    },
  },
})

type IPrimitiveIcon = {
  height?: number | string
  width?: number | string
  fill?: string
  color?: string
  size?: number | string
  stroke?: string
  as?: React.ElementType
  className?: string
  classNameColor?: string
}

const PrimitiveIcon = React.forwardRef<
  React.ElementRef<typeof Svg>,
  IPrimitiveIcon
>(
  (
    {
      height,
      width,
      fill,
      color,
      classNameColor,
      size,
      stroke,
      as: AsComp,
      ...props
    },
    ref
  ) => {
    color = color ?? classNameColor
    const sizeProps = useMemo(() => {
      if (size) return { size }
      if (height && width) return { height, width }
      if (height) return { height }
      if (width) return { width }
      return {}
    }, [size, height, width])

    let colorProps = {}
    if (fill) {
      colorProps = { ...colorProps, fill: fill }
    }
    if (stroke !== "currentColor") {
      colorProps = { ...colorProps, stroke: stroke }
    } else if (stroke === "currentColor" && color !== undefined) {
      colorProps = { ...colorProps, stroke: color }
    }

    if (AsComp) {
      return <AsComp ref={ref} {...props} {...sizeProps} {...colorProps} />
    }
    return (
      <Svg ref={ref} height={height} width={width} {...colorProps} {...props} />
    )
  }
)

const UISelect = createSelect(
  {
    Root: View,
    Trigger:
      Platform.OS === "web"
        ? withStyleContext(SelectTriggerWrapper)
        : withStyleContextAndStates(SelectTriggerWrapper),
    Input: TextInput,
    Icon: PrimitiveIcon,
  },
  {
    Portal: Actionsheet,
    Backdrop: ActionsheetBackdrop,
    Content: ActionsheetContent,
    DragIndicator: ActionsheetDragIndicator,
    DragIndicatorWrapper: ActionsheetDragIndicatorWrapper,
    Item: ActionsheetItem,
    ItemText: ActionsheetItemText,
    ScrollView: ActionsheetScrollView,
    VirtualizedList: ActionsheetVirtualizedList,
    FlatList: ActionsheetFlatList,
    SectionList: ActionsheetSectionList,
    SectionHeaderText: ActionsheetSectionHeaderText,
  }
)

cssInterop(UISelect, { className: "style" })
cssInterop(UISelect.Input, {
  className: { target: "style", nativeStyleToProp: { textAlign: true } },
})
cssInterop(SelectTriggerWrapper, { className: "style" })
//@ts-ignore
cssInterop(UISelect.Icon, {
  className: {
    target: "style",
    nativeStyleToProp: {
      height: true,
      width: true,
      fill: true,
      color: "classNameColor",
      stroke: true,
    },
  },
})

type ISelectProps = VariantProps<typeof selectStyle> &
  React.ComponentProps<typeof UISelect> & { className?: string }

const Select = React.forwardRef<
  React.ElementRef<typeof UISelect>,
  ISelectProps
>(({ className, ...props }, ref) => {
  return (
    <UISelect
      className={selectStyle({
        class: className,
      })}
      ref={ref}
      {...props}
    />
  )
})

type ISelectTriggerProps = VariantProps<typeof selectTriggerStyle> &
  React.ComponentProps<typeof UISelect.Trigger> & { className?: string }

const SelectTrigger = React.forwardRef<
  React.ElementRef<typeof UISelect.Trigger>,
  ISelectTriggerProps
>(({ className, size = "md", variant = "outline", ...props }, ref) => {
  return (
    <UISelect.Trigger
      className={selectTriggerStyle({
        class: className,
        size,
        variant,
      })}
      ref={ref}
      context={{ size, variant }}
      {...props}
    />
  )
})

type ISelectInputProps = VariantProps<typeof selectInputStyle> &
  React.ComponentProps<typeof UISelect.Input> & { className?: string }

const SelectInput = React.forwardRef<
  React.ElementRef<typeof UISelect.Input>,
  ISelectInputProps
>(({ className, ...props }, ref) => {
  const { size: parentSize, variant: parentVariant } = useStyleContext()
  return (
    <UISelect.Input
      className={selectInputStyle({
        class: className,
        parentVariants: {
          size: parentSize,
          variant: parentVariant,
        },
      })}
      ref={ref}
      {...props}
    />
  )
})

type ISelectIcon = VariantProps<typeof selectIconStyle> &
  React.ComponentProps<typeof UISelect.Icon> & { className?: string }

const SelectIcon = React.forwardRef<
  React.ElementRef<typeof UISelect.Icon>,
  ISelectIcon
>(({ className, size, ...props }, ref) => {
  const { size: parentSize } = useStyleContext()
  if (typeof size === "number") {
    return (
      <UISelect.Icon
        ref={ref}
        {...props}
        className={selectIconStyle({ class: className })}
        size={size}
      />
    )
  } else if (
    (props?.height !== undefined || props?.width !== undefined) &&
    size === undefined
  ) {
    return (
      <UISelect.Icon
        ref={ref}
        {...props}
        className={selectIconStyle({ class: className })}
      />
    )
  }
  return (
    <UISelect.Icon
      className={selectIconStyle({
        class: className,
        size,
        parentVariants: {
          size: parentSize,
        },
      })}
      ref={ref}
      {...props}
    />
  )
})

Select.displayName = "Select"
SelectTrigger.displayName = "SelectTrigger"
SelectInput.displayName = "SelectInput"
SelectIcon.displayName = "SelectIcon"

// Actionsheet Components
const SelectPortal = UISelect.Portal
const SelectBackdrop = UISelect.Backdrop
const SelectContent = UISelect.Content
const SelectDragIndicator = UISelect.DragIndicator
const SelectDragIndicatorWrapper = UISelect.DragIndicatorWrapper
const SelectItem = UISelect.Item
const SelectItemText = UISelect.ItemText
const SelectScrollView = UISelect.ScrollView
const SelectVirtualizedList = UISelect.VirtualizedList
const SelectFlatList = UISelect.FlatList
const SelectSectionList = UISelect.SectionList
const SelectSectionHeaderText = UISelect.SectionHeaderText

export {
  Select,
  SelectTrigger,
  SelectInput,
  SelectIcon,
  SelectPortal,
  SelectBackdrop,
  SelectContent,
  SelectDragIndicator,
  SelectDragIndicatorWrapper,
  SelectItem,
  SelectItemText,
  SelectScrollView,
  SelectVirtualizedList,
  SelectFlatList,
  SelectSectionList,
  SelectSectionHeaderText,
}

Step 3: Update the import paths to match your project setup.

API Reference

To use this component in your project, include the following import statement in your file.

import {
  Select,
  SelectTrigger,
  SelectInput,
  SelectIcon,
  SelectPortal,
  SelectBackdrop,
  SelectContent,
  SelectDragIndicatorWrapper,
  SelectDragIndicator,
  SelectItem,
} from "@/components/ui/select"

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.

Important Note

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.
selectedValue	boolean	false	Sets the currently selected option value, allowing the component to render with the corresponding option pre-selected.
initialLabel	string	-	Sets the initial selected Label for a select component.
defaultValue	boolean	false	Sets the initial selected option value for a select component.
onOpen	() => any	-	Callback to be invoked when Select Dropdown or Actionsheet is opened.
onValueChange	() => any	-	Callback to be invoked when Select value is changed.
onClose	() => any	-	Callback to be invoked when Select Dropdown or Actionsheet is closed.

Important Note

Note: Please note that if you want to use initialLabel prop, then you also need to pass defaultValue or selectedValue prop, to select the option value for a select component.

SelectTrigger

It inherits all the properties of React Native's Pressable 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.

Important Note

Note: If snapPoints are not provided to SelectPortal, then it's essential to set maxHeight to SelectContent.

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.

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.
textStyle	inherits all the properties of react native text	-	This prop only works on native.

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.

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

Props

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

Select

Name	Value	Default
size	sm \| md \| lg \| xl	md
variant	underlined \| outline \| rounded	outline

Data Attributes Table

Component receives states as props as boolean values, which are applied as data-* attributes. These attributes are then used to style the component via classNames, enabling state-based styling.

State	Data Attribute	Values
hover	data-hover	true \| false
disabled	data-disabled	true \| false
focus	data-focus	true \| false
invalid	data-invalid	true \| false

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 className="mr-3" as={ChevronDownIcon} />
    </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>

Select

Installation

Run the following command:

Step 1: Install the following dependencies:

Step 2: Copy and paste the following code into your project.

Step 3: Update the import paths to match your project setup.

API Reference

Component Props

Select

SelectTrigger

SelectInput

SelectIcon

SelectPortal

SelectBackdrop

SelectContent

SelectDragIndicatorWrapper

SelectDragIndicator

SelectItem

SelectScrollView

SelectVirtualizedList

SelectFlatList

SelectSectionList

SelectSectionHeaderText

Features

Accessibility

Keyboard

Screen Reader

Props

Select

Data Attributes Table

Examples

Select FormControlled