Select

<>
  <Label htmlFor="author">Select an author</Label>
  <Select id="author">
    <Option value="baldwin">James Baldwin</Option>
    <Option value="brown">adrienne maree brown</Option>
    <Option value="butler">Octavia Butler</Option>
    <Option value="coates">Ta-Nehisi Coates</Option>
    <Option value="lorde">Audre Lorde</Option>
    <Option value="nnedi">Nnedi Okorafor</Option>
  </Select>
</>

A select allows users to select an option from a list in a form field. It is used with the Label and Help Text components.

Select allows a user to make a selection from a list of options in a form field. By default, it will show the first option in the list. However, you can also set a different pre-selected option from your list to show.

At its most basic, a Select has an options list that’s styled according to the browser default. A Combobox has a Twilio-styled options list and can allow for additional functionality like typeahead.

Use a Select when:

• You need a native picker experience, especially on mobile devices.
• Users will be selecting from a list of 4-10 options, or a sorted list of highly familiar options, like an alphabetical list of states or countries.
• You need the component to work out-of-the-box across all operating systems and browsers.

Use a Combobox when:

• You need a Twilio-styled options list.
• You need to show more than text in an option, like text paired with an icon.
• Users would benefit from typeahead functionality. For example, typeahead may be useful when users need to select from a list of more than 10 options.
• You need to lazy load a much longer list of options to improve page load performance.

• Include a visible label on all form fields.
• Each label must use the htmlFor prop that equals the id of the associated input.
• Label a form field using one of these methods:
  • Visible label with Label (preferred)
  • Visible label that's associated to the input with aria-labelledby
  • Label directly using aria-label
• Provide clear identification of required fields in the label or at the start of a form. If you use the required field indicator, include the form key at the start of the form.
  • Use the required prop to programatically indicate they are required to browsers.
• Include inline error text with the error icon on any field that errors to make it visually clear that the field changed.
• If the input has assicated help text or error text, include the aria-describedby prop on the input. This should match the id of the help or error text.

The base Select is the input without any supporting elements (e.g., label, help text, etc).

• Options — The list of items contained in a Select
• Selected value — (Optional) The value that appears in the select on page load. By default, this is the first option in the list.

The Select will fill the width of the container it’s placed in.

<>
  <Label htmlFor="author">Select an author</Label>
  <Select id="author">
    <Option value="baldwin">James Baldwin</Option>
    <Option value="brown">adrienne maree brown</Option>
    <Option value="butler">Octavia Butler</Option>
    <Option value="coates">Ta-Nehisi Coates</Option>
    <Option value="lorde">Audre Lorde</Option>
    <Option value="nnedi">Nnedi Okorafor</Option>
  </Select>
</>

The Select component should include the base Select, along with supporting elements to compose a Select form field that gives the user the context they need to successfully fill it out.

• Label — A label should be included for every form field and provide a short title for its associated input.
• Required field indicator — In a form where there are fewer or as many required fields as optional, use a required indicator to show users which fields are required to be filled out.
• Optional field indicator — In a form where there are more required fields than optional fields, use an optional indicator to show users which fields they don’t have to fill out. In general, ask for information only when needed. Consider removing the optional fields.
• Help text — Text that’s placed below the field to help users prevent an error and describe what makes the form field successful.

<>
  <Label htmlFor="select_product_demo" required>Select a product</Label>
  <Select id="select_product_demo" htmlFor="select_product_demo" required>
    <Option value="messaging">SMS</Option>
    <Option value="numbers">Phone Numbers</Option>
    <Option value="video">Video</Option>
  </Select>
  <HelpText variant="default">Choose a Twilio product.</HelpText>
</>

• Prefix/suffix text - Text that can be used as a prefix or suffix to the value that is entered. Use prefix/suffix to help users format text.
• Icon - Icons that can be placed in the same area as the prefix and suffix text. Icons should trigger an action (e.g., opening a popover).

<>
  <Label htmlFor="select_add_ons_prefix_demo">Phone number</Label>
  <Select
    id="select_add_ons_prefix_demo"
    htmlFor="select_add_ons_prefix_demo"
    insertBefore={<Text color="colorTextWeak" as="span" fontWeight="fontWeightSemibold">+1</Text>}
  >
    <Option value="cats">(415) 555-CATS</Option>
    <Option value="dogs">(415) 555-DOGS</Option>
    <Option value="mice">(415) 555-MICE</Option>
  </Select>
  <HelpText variant="default">Select with prefix.</HelpText>
</>

<>
  <Label htmlFor="select_add_ons_suffix_demo">Phone number</Label>
  <Select
    id="select_add_ons_suffix_demo"
    htmlFor="select_add_ons_suffix_demo"
    insertAfter={
      <Button variant="link">
        <InformationIcon decorative={false} size="sizeIcon20" title="Get more info" />
      </Button>
    }
  >
    <Option value="cats">(415) 555-CATS</Option>
    <Option value="dogs">(415) 555-DOGS</Option>
    <Option value="mice">(415) 555-MICE</Option>
  </Select>
  <HelpText variant="default">Select with suffix.</HelpText>
</>

To be consistent with React's documentation on best practices for native select elements, the selected attribute is not allowed in the API. You can instead select a defaultValue property for the select.

<>
  <Label htmlFor="default_value_demo" required>Phone number</Label>
  <Select
    id="default_value_demo"
    htmlFor="default_value_demo"
    defaultValue="dogs"
  >
    <Option value="cats">(415) 555-CATS</Option>
    <Option value="dogs">(415) 555-DOGS</Option>
    <Option value="mice">(415) 555-MICE</Option>
  </Select>
</>

Use an OptionGroup to create groupings of options within the select element.

• label - String that will be used as the group label, this is required.

<>
  <Label htmlFor="option_group_demo" required>Product offering</Label>
  <Select
    id="option_group_demo"
    htmlFor="option_group_demo"
  >
    <OptionGroup label="SMS">
        <Option value="geomatch">Area-code geomatch</Option>
        <Option value="channels">Channels</Option>
        <Option value="short-codes">Short codes</Option>
    </OptionGroup>
    <OptionGroup label="Voice">
        <Option value="conference">Conference</Option>
        <Option value="recording">Recordings</Option>
        <Option value="tts">Text to Speech</Option>
    </OptionGroup>
    <OptionGroup label="Video">
        <Option value="hipaa">HIPAA eligibility</Option>
        <Option value="p2p">Peer to peer</Option>
        <Option value="recordings">Recordings</Option>
    </OptionGroup>
  </Select>
  <HelpText variant="default">Select a product to learn more.</HelpText>
</>

Avoid errors on selects by removing or disabling invalid options from the list of options.

If a user is able to choose an invalid option, change a Select to its error state and use Help Text to add an inline error. The Help Text inline error is placed below the field to inform a user of any errors in their value. If help text exists, the error text should replace and repeat the help text.

<>
  <Label htmlFor="inline_error_demo">Emergency caller ID</Label>
  <Select
    id="inline_error_demo"
    htmlFor="inline_error_demo"
    hasError
  >
    <Option value="cats">(415) 555-CATS</Option>
    <Option value="dogs">(415) 555-DOGS</Option>
    <Option value="mice">(415) 555-MICE</Option>
  </Select>
  <HelpText variant="error">The number you have selected is not configured for emergency calling.</HelpText>
</>

Use a disabled option as the default selected value if you have no valid option to safely default to and the field is required.

Otherwise, use disabled options sparingly. Most browsers show disabled option text with low contrast, so consider other ways you could communicate that an option is unavailable, if you need to at all.

<>
  <Label htmlFor="disabled_options_demo">Phone number capability</Label>
  <Select
    id="disabled_options_demo"
    htmlFor="disabled_options_demo"
  >
    <Option disabled value="fax">Fax</Option>
    <Option disabled value="voice">Voice</Option>
    <Option value="sms">SMS</Option>
  </Select>
  <HelpText variant="default">Some options in this select are disabled.</HelpText>
</>

Use a disabled form field to show users that they can’t interact with the field.

If you want to show information that can’t be edited, use a read-only Input or consider another way of showing static information.

<>
  <Label htmlFor="disabled_select_demo" disabled>Phone number capabilities</Label>
  <Select
    id="disabled_select_demo"
    htmlFor="disabled_select_demo"
    disabled
  >
    <Option value="fax">Fax</Option>
    <Option value="voice">Voice</Option>
    <Option value="sms">SMS</Option>
  </Select>
  <HelpText variant="default">This select is currently disabled.</HelpText>
</>

A select field should be composed with at least a label and a select.

Stack form fields vertically with $space-80 spacing between each field.

<>
  <Box marginBottom="space80">
    <Label htmlFor="voice_callback_method">HTTP method</Label>
    <Select required id="voice_callback_method">
        <Option value="get">GET</Option>
        <Option value="post">POST</Option>
        <Option value="put">PUT</Option>
    </Select>
  </Box>
  <Box>
    <Label htmlFor="voice_callback">Primary Voice callback</Label>
    <Input id="voice_callback" name="voice_callback" type="text" placeholder="https://demo.twilio.com/welcome/voice/" onChange={() => {}} required/>
  </Box>
</>

Avoid placing multiple form fields on the same horizontal row to help make it easier to scan a page vertically. Use the Grid component if you need to place form fields horizontally.

Keep option text concise and simple. Option text will truncate when it’s longer than the width of the container. If choosing options requires more explanation, consider using a Radio Group instead and add help text for each option, or give more explanation through help text.

Use a safe and reversible option as the default selected value, or an option that tells users to choose from the list. For example, on page load, a select could show “Choose category" as the default value if there’s no safe default.

Use 4-10 options in a select, or a sorted list of highly familiar options (e.g., alphabetical list of states), since selects don’t allow for searching or filtering through options. Sort options logically (e.g., alphabetically, by value) or in an order that’s intuitive to your user.

Labels should clearly describe the value being requested. They should be concise and descriptive, not instructional. To do this:

• Use help text to provide instruction if needed. For example, don’t use “Choose a nickname for your reference only” as label text. Instead, use “Nickname” as a label and “Nickname is for your reference only. This won’t be displayed to recipients.” as help text.
• Avoid articles (“a”, “the”) and punctuation. For example, use “SIM registration code” rather than “The SIM registration code”.

To support internationalization, avoid starting a sentence with the label and using the field to finish it since sentence structures vary across languages. For example, use “Call log expiration date” or “How long should logs be stored?”. Don’t use “Remove logs after:”.

Give users enough information in help text to prevent input and formatting errors. Keep it concise and scoped to information that will help with validation. For example, use help text if a password field has specific requirements that a user should know prior to filling it out.

If you need to use more than two sentences to explain a field, link out to supporting docs or trigger a popover instead.

Ask for information only when needed. Consider removing the field otherwise.

In a form where there are fewer optional fields than required, use an optional indicator to show users which fields they don’t have to fill out. Otherwise, use required indicators to show users which fields they must fill out.

If a field is required and there’s no safe default selected value, default to a disabled option that tells users to choose an option (e.g., “Choose categories”). However, if the field is optional and there’s no safe default, keep the option enabled so that users can unselect.

Disable or remove any options in a select that would result in an error if possible. Validate form fields on form submission.

Don’t prevent form submission by disabling the submit button. A disabled button cannot be detected by assistive technologies. Use An error messages to explain what information is missing or incorrect.

Disable or remove any options in a select that would result in an error if possible. If an error occurs, use Help Text to show an inline error that explains how to fix the error.

For additional guidance on how to compose error messages, refer to the error state pattern.

• Prefix/suffix — Use a prefix or suffix to help users format their input and to provide more context about the value a user is entering. For example, you could prefix or suffix a field with a currency symbol. Make sure to consider internationalization when using prefixes or suffixes since formatting may differ across languages. For example, currency symbols are placed on the left in American English, while they're placed on the right in French. Don't use prefix/suffix text as a replacement for a label.
• Icon — Use an icon if you need to give the user additional controls for the field. For example, use an icon to clear a field on click, removing the need for users to manually delete their entered value. Place icon buttons that trigger an action on the right side of the field. If you need 2 actions on a field (e.g., popover trigger and clear field), place the icon button that affects the field value on the right, and the other icon on the left.

Use a select when:

• You need a native picker experience, especially on mobile devices.
• You need the component to work out-of-the-box across all operating systems and browsers.