Select

<View width="300px" maxWidth="100%">
  <Select options={[{ label: "Following", value: "1" }, { label: "Popular", value: "2" }, { label: "New & Noteworthy", value: "3" }]} name="sort" placeholder="Sort by" />
</View>

Form fields require a name property, making it the only property needed to start using Select. To handle change events, add an onChange property.

<Select
  name="animal"
  placeholder="Select an animal"
  onChange={(args) => console.log(args)}
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
/>

Like native inputs in React, Select can be used as a controlled or uncontrolled component. By default, Select is uncontrolled and allows you to define its default value using the defaultValue property. In this case, all change events are handled automatically. This approach is useful when setting the field's default value from a data source without needing manual control afterward.

<Select
  name="animal2"
  placeholder="Select an animal"
  defaultValue="dog"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
/>

To manually control the state of the field, use the value property. This provides complete control over the component value and disables automatic value handling. You must update the state using the onChange handler, allowing you to add custom logic before the update occurs.

<Select
  name="animal3"
  placeholder="Select an animal"
  onChange={({ value }) => {
    /* Update your state here */
  }}
  value="dog"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
/>

Select supports a content slot on the left side, allowing you to display text or other components.

<Select
  name="animal6"
  placeholder="Select account"
  options={[
    { label: "hello@reshaped.so", value: "1" },
    { label: "updates@reshaped.so", value: "2" },
  ]}
  startSlot={<Avatar src="/img/examples/avatar-3.png" initials="P" size={5} />}
/>

For consistent icon usage in form fields, use the icon property instead of startSlot and pass the icon SVG component.

<Select
  name="animal"
  placeholder="Select an animal"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
  icon={IconZap}
/>

Select comes in three sizes, with medium as the default. All sizes align with other related components like Button and TextField.

<View gap={3}>
  <Select
    size="medium"
    name="animal"
    placeholder="Select an animal"
    options={[
      { label: "Dog", value: "dog" },
      { label: "Turtle", value: "turtle" },
    ]}
    icon={IconZap}
  />
  <Select
    size="large"
    name="animal"
    placeholder="Select an animal"
    options={[
      { label: "Dog", value: "dog" },
      { label: "Turtle", value: "turtle" },
    ]}
    icon={IconZap}
  />
  <Select
    size="xlarge"
    name="animal"
    placeholder="Select an animal"
    options={[
      { label: "Dog", value: "dog" },
      { label: "Turtle", value: "turtle" },
    ]}
    icon={IconZap}
  />
</View>

To change the style of the Select, you can use its faded variant.

<Select
  variant="faded"
  name="animal"
  placeholder="Select an animal"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
  icon={IconZap}
/>

Alternatively, use the headless variant to remove most styles from the Select, allowing for custom layouts.

<Select
  variant="headless"
  name="animal"
  placeholder="Select an animal"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
  icon={IconZap}
/>

headless variant removes the focused and error outlines, as you may want to display them elsewhere. Use the :focus-within selector in your CSS to implement the focus state.

Use the hasError property to indicate that the Select is not passing form validation.

<Select
  name="animal4"
  placeholder="Select an animal"
  hasError
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
/>

Select can be disabled using the disabled flag. Note that disabling the field will exclude it from the form submit query.

<Select
  disabled
  name="animal5"
  placeholder="Select an animal"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
/>

Use Select without passing options to render only the trigger as a button. This allows you to combine it with other components like DropdownMenu or Modal.

<DropdownMenu width="trigger">
  <DropdownMenu.Trigger>
    {(attributes) => (
      <Select
        name="animal"
        placeholder="Select an animal"
        inputAttributes={attributes}
      />
    )}
  </DropdownMenu.Trigger>
  <DropdownMenu.Content>
    <DropdownMenu.Item>Turtle</DropdownMenu.Item>
    <DropdownMenu.Item>Cat</DropdownMenu.Item>
  </DropdownMenu.Content>
</DropdownMenu>

To inform the user of the expected data, add labels or status messages to your fields using the FormControl utility. When using the xlarge Select size, combine it with the large FormControl size for better visual alignment.

<FormControl>
  <FormControl.Label>Email</FormControl.Label>
  <Select
    name="animal7"
    placeholder="Select an animal"
    options={[
      { label: "Dog", value: "dog" },
      { label: "Turtle", value: "turtle" },
    ]}
  />
</FormControl>

Select supports responsive syntax for the size property. Use object syntax to control its value based on the viewport size. Responsive properties are mobile-first, so selecting a value for a viewport will also apply it to all wider viewports.

<Select size={{ s: 'medium', l: 'large' }}>

• When using Select, ensure to provide a text description for it. You can provide the label using the FormControl utility or pass inputAttributes={{ 'aria-label': 'Your label' }} to the component if you don't want to display it visually.

<Select
  name="animal8"
  placeholder="Select an animal"
  options={[
    { label: "Dog", value: "dog" },
    { label: "Turtle", value: "turtle" },
  ]}
  inputAttributes={{ "aria-label": "Animal" }}
/>