Dropdown

A pull-down list of items that appear when the input is selected.

UsageGuidelinesAPI

Use Dropdown...

To display a list with plain text.
To leverage the native browser select functionality.
To select a single item from a larger set of items.
To submit data within a form.

Don't use Dropdown...

To display complex information like titles, sections, thumbnail images, or callouts. Use a Listbox instead.
To display links. Use a Menu instead.

Dropdown is built using the native HTML select element, so the appearance of its Dropdown list is determined by the user's browser and device.

Skin

Default

The default Dropdown is styled like other form elements and displays the first option within the Dropdown list.

ReactVanilla

<Dropdown>
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<Dropdown>
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<select class="swan-dropdown">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

<select class="swan-dropdown">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

Line

skin="line" is deprecated in SWAN v3.3
Use the skin="standard" instead, which aligns with new semantic roles on SWAN components.

ReactVanilla

<Dropdown skin="line">
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<Dropdown skin="line">
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<select class="swan-dropdown swan-dropdown-skin-line">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

<select class="swan-dropdown swan-dropdown-skin-line">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

Size

size is deprecated in SWAN v3.3

The component now automatically handles sizing based on the selected mode(standardMode/compactMode). Please update your implementation to rely on the new mode-based sizing.

Use size="mini" to reduce the height of a Dropdown.

The "mini" Dropdown should play a supporting role in the layout, ensuring a clear visual hierarchy. This size works well in situations where there is limited vertical space.

ReactVanilla

<Dropdown size="mini">
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<Dropdown size="mini">
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<select class="swan-dropdown swan-dropdown-mini">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

<select class="swan-dropdown swan-dropdown-mini">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

Full width

Use fullWidth to grow a Dropdown to fill its container.

ReactVanilla

<Dropdown fullWidth>
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<Dropdown fullWidth>
  <DropdownOption value="A">Option A</DropdownOption>
  <DropdownOption value="B">Option B</DropdownOption>
  <DropdownOption value="C">Option C</DropdownOption>
</Dropdown>

<select class="swan-dropdown swan-dropdown-full-width">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

<select class="swan-dropdown swan-dropdown-full-width">
  <option value="A">Option A</option>
  <option value="B">Option B</option>
  <option value="C">Option C</option>
</select>

With floating label

An alternate way to display the dropdown with the label positioned inside it, above the selection. To achieve that, use the component InputWithFloatingLabel.

ReactVanilla

<InputWithFloatingLabel>
  <FloatingLabel>Flavor</FloatingLabel>
  <Dropdown>
    <DropdownOption value="vanilla">Vanilla</DropdownOption>
    <DropdownOption value="strawberry">Strawberry</DropdownOption>
    <DropdownOption value="chocolate">Chocolate</DropdownOption>
  </Dropdown>
</InputWithFloatingLabel>

<InputWithFloatingLabel>
  <FloatingLabel>Flavor</FloatingLabel>
  <Dropdown>
    <DropdownOption value="vanilla">Vanilla</DropdownOption>
    <DropdownOption value="strawberry">Strawberry</DropdownOption>
    <DropdownOption value="chocolate">Chocolate</DropdownOption>
  </Dropdown>
</InputWithFloatingLabel>

<div class="swan-vanilla-ignore swan-input-with-floating-label">
  <select class="swan-dropdown" id="some-id">
    <option value="vanilla">Vanilla</option>
    <option value="strawberry">Strawberry</option>
    <option value="chocolate">Chocolate</option></select
  ><label class="swan-label" for="some-id">Flavor</label>
</div>

<div class="swan-vanilla-ignore swan-input-with-floating-label">
  <select class="swan-dropdown" id="some-id">
    <option value="vanilla">Vanilla</option>
    <option value="strawberry">Strawberry</option>
    <option value="chocolate">Chocolate</option></select
  ><label class="swan-label" for="some-id">Flavor</label>
</div>

Disabled

Usedisabled onDropdown to prevent it from being opened; when it is dependent on a prior user action.

Use disabledon DropdownOption to indicate that individual options are not relevant or available within the user's current context.

ReactVanilla

<FlexBox flexWrap="wrap" gap="between-actions">
  <Box>
    <Dropdown disabled>
      <DropdownOption value="A">Option A</DropdownOption>
      <DropdownOption value="B">Option B</DropdownOption>
      <DropdownOption value="C">Option C</DropdownOption>
    </Dropdown>
  </Box>
  <Box>
    <Dropdown>
      <DropdownOption value="A">Option A</DropdownOption>
      <DropdownOption disabled value="B">
        Option B
      </DropdownOption>
      <DropdownOption value="C">Option C</DropdownOption>
    </Dropdown>
  </Box>
</FlexBox>

<FlexBox flexWrap="wrap" gap="between-actions">
  <Box>
    <Dropdown disabled>
      <DropdownOption value="A">Option A</DropdownOption>
      <DropdownOption value="B">Option B</DropdownOption>
      <DropdownOption value="C">Option C</DropdownOption>
    </Dropdown>
  </Box>
  <Box>
    <Dropdown>
      <DropdownOption value="A">Option A</DropdownOption>
      <DropdownOption disabled value="B">
        Option B
      </DropdownOption>
      <DropdownOption value="C">Option C</DropdownOption>
    </Dropdown>
  </Box>
</FlexBox>

<div class="swan-vanilla-ignore swan-input-with-floating-label">
  <select class="swan-dropdown" id="some-id">
    <option value="vanilla">Vanilla</option>
    <option value="strawberry">Strawberry</option>
    <option value="chocolate">Chocolate</option></select
  ><label class="swan-label" for="some-id">Flavor</label>
</div>

<div class="swan-vanilla-ignore swan-input-with-floating-label">
  <select class="swan-dropdown" id="some-id">
    <option value="vanilla">Vanilla</option>
    <option value="strawberry">Strawberry</option>
    <option value="chocolate">Chocolate</option></select
  ><label class="swan-label" for="some-id">Flavor</label>
</div>

Forms: Error messaging, helper text, and external labels

Dropdown errors, helper text, and external labels should use the standard Form component.

Vanilla API

Refer to Form for more details

React API

In React API, use the FormField components to incorporate external labels, error messages, or helper text. These components automatically apply the necessary aria attributes to the Dropdown, eliminating the need for manual handling.g.

Note that FormField components provide minimal styling, and it's recommended to nest FormField within a StandardForm for the desired look.

Inspecting the DOM reveals that FormLabel automatically sets a for attribute to the Dropdown's ID, and the Dropdown's aria-describedby prop is set to the FormHelper's ID.

ReactVanilla

<StandardForm>
  <FormField>
    <FormLabel>
      Favorite animal <FormLabelOptional>(Optional)</FormLabelOptional>
    </FormLabel>
    <FormInputGroup>
      <Dropdown>
        <DropdownOption>Panda</DropdownOption>
        <DropdownOption>Otter</DropdownOption>
        <DropdownOption>Kitten</DropdownOption>
      </Dropdown>
      <FormHelper>There is no wrong answer</FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>
      Favorite animal <FormLabelOptional>(Optional)</FormLabelOptional>
    </FormLabel>
    <FormInputGroup>
      <Dropdown>
        <DropdownOption>Panda</DropdownOption>
        <DropdownOption>Otter</DropdownOption>
        <DropdownOption>Kitten</DropdownOption>
      </Dropdown>
      <FormHelper>There is no wrong answer</FormHelper>
    </FormInputGroup>
  </FormField>
</StandardForm>

<form class="swan-form">
  <div>
    <label class="swan-label" for="auto-id-o1ubgzux0-70"
      >Favorite animal
      <span class="swan-label-optional">(Optional)</span></label
    >
    <div class="swan-input-group">
      <select aria-invalid="false" class="swan-dropdown">
        <option>Panda</option>
        <option>Otter</option>
        <option>Kitten</option>
      </select>
      <p class="swan-input-group-helper-text" id="auto-id-o1ubgzux0-71">
        There is no wrong answer
      </p>
    </div>
  </div>
</form>

<form class="swan-form">
  <div>
    <label class="swan-label" for="auto-id-o1ubgzux0-70"
      >Favorite animal
      <span class="swan-label-optional">(Optional)</span></label
    >
    <div class="swan-input-group">
      <select aria-invalid="false" class="swan-dropdown">
        <option>Panda</option>
        <option>Otter</option>
        <option>Kitten</option>
      </select>
      <p class="swan-input-group-helper-text" id="auto-id-o1ubgzux0-71">
        There is no wrong answer
      </p>
    </div>
  </div>
</form>

In the presence of a FormError, the Dropdown automatically adopts an error-state appearance without requiring additional props. Inspecting the DOM reveals that the aria-errormessage and aria-describedby props on the Dropdown are automatically set.

ReactVanilla

<StandardForm>
  <FormField>
    <FormLabel>Favorite animal</FormLabel>
    <FormInputGroup>
      <Dropdown>
        <DropdownOption hidden disabled>
          Select an animal
        </DropdownOption>
        <DropdownOption>Panda</DropdownOption>
        <DropdownOption>Otter</DropdownOption>
        <DropdownOption>Kitten</DropdownOption>
      </Dropdown>
      <FormError>You must make a selection</FormError>
    </FormInputGroup>
  </FormField>
</StandardForm>

<StandardForm>
  <FormField>
    <FormLabel>Favorite animal</FormLabel>
    <FormInputGroup>
      <Dropdown>
        <DropdownOption hidden disabled>
          Select an animal
        </DropdownOption>
        <DropdownOption>Panda</DropdownOption>
        <DropdownOption>Otter</DropdownOption>
        <DropdownOption>Kitten</DropdownOption>
      </Dropdown>
      <FormError>You must make a selection</FormError>
    </FormInputGroup>
  </FormField>
</StandardForm>

<form class="swan-form">
  <div>
    <label class="swan-label" for="auto-id-o1ubgzux0-72">Favorite animal</label>
    <div class="swan-input-group">
      <select
        aria-invalid="true"
        class="swan-dropdown swan-dropdown-skin-error"
      >
        <option hidden="" disabled="">Select an animal</option>
        <option>Panda</option>
        <option>Otter</option>
        <option>Kitten</option>
      </select>
      <p class="swan-input-group-error-text" id="auto-id-o1ubgzux0-73">
        You must make a selection
      </p>
    </div>
  </div>
</form>

<form class="swan-form">
  <div>
    <label class="swan-label" for="auto-id-o1ubgzux0-72">Favorite animal</label>
    <div class="swan-input-group">
      <select
        aria-invalid="true"
        class="swan-dropdown swan-dropdown-skin-error"
      >
        <option hidden="" disabled="">Select an animal</option>
        <option>Panda</option>
        <option>Otter</option>
        <option>Kitten</option>
      </select>
      <p class="swan-input-group-error-text" id="auto-id-o1ubgzux0-73">
        You must make a selection
      </p>
    </div>
  </div>
</form>

Managing state

As is the case with most form elements, folks often want to "control" this component. Controlling a component means that you take ownership over its state rather than letting the browser manage the state for you. When you control a component, you own the source of truth for the UI. This means that you don't need to query the DOM in order to determine the current value of the element. So, when it comes time to use the value of the element somewhere else (e.g. submitting the selection to a back-end service) you can trust your stored value.

To control a Dropdown, store the selected value (e.g., in React state or a Redux store) and provide a handler to update this value when users interact with the component.

const MyDropdown = props => {
  const [selectedValue, setSelectedValue] = React.useState('A')

  return (
    <Dropdown
      value={selectedValue}
      onChange={event => setSelectedValue(event.target.value)}
    >
      <DropdownOption value="A">A</DropdownOption>
      <DropdownOption value="B">B</DropdownOption>
      <DropdownOption value="C">C</DropdownOption>
    </Dropdown>
  )
}

const MyDropdown = props => {
  const [selectedValue, setSelectedValue] = React.useState('A')

  return (
    <Dropdown
      value={selectedValue}
      onChange={event => setSelectedValue(event.target.value)}
    >
      <DropdownOption value="A">A</DropdownOption>
      <DropdownOption value="B">B</DropdownOption>
      <DropdownOption value="C">C</DropdownOption>
    </Dropdown>
  )
}

If you don't need to manage the state of the Dropdown, you can omit the value and onChange props, allowing the browser to handle the state. Consider using the defaultValue prop to specify the initial selected value.

Implementation

For the Vanilla API, if your Dropdown is created after the DOMready event, initialize it by triggering an initializeControl event on it.

Avoid placing a Dropdown inside an element that is a table cell or has CSS display: table-cell. This configuration may result in the Dropdown being rendered more narrowly than its actual minimum width.

Accessibility

See accessibility details for Forms.

Number of listed items

Do

Use a Dropdown when listing 5 or more items.

Dont

Use a Dropdown when listing fewer than 4 items. Use a single select Section Set instead, with radio buttons if space permits.

Dont

Use a Dropdown when listing more than 15 items. This can create a lack of overview and potential scrolling issues. Use a Combobox instead.

Placement

The Dropdown prioritizes usability through generous padding and a large font, resulting in a minimum width determined by the widest option within the Dropdown.

Ensure the Dropdown has sufficient room for rendering on the page.
Account for the potential length increase in translated text compared to English to prevent display issues.

Props

Dropdown

This component is implemented using the <select /> as the root element. You can utilize the native attributes supported by <select /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
skin	`"standard" \| "line" \| "error" \| null`	false	The error skin will show a red border around the element. skin 'line' is deprecated. Use 'standard' instead	standard
size	`"standard" \| "mini" \| null`	false	⚠️ Deprecated - This is deprecated without a replacement. Mini will make the dropdown smaller	standard
fullWidth	`boolean \| null`	false	whether or not the component should horizontally to fill its container's availableWidth	false
htmlSize	`number`	false	Specifies the number of visible options in a drop-down list, corresponding to the HTML `size` attribute.	null

DropdownFloatingLabel

This component is implemented using the <label /> as the root element. You can utilize the native attributes supported by <label /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

DropdownOption

This component is implemented using the <option /> as the root element. You can utilize the native attributes supported by <option /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

DropdownWithFloatingLabel

This component is implemented using the <div /> as the root element. You can utilize the native attributes supported by <div /> tag. The ref is directly assigned to the root element, allowing you to access and manipulate it as needed.

See core props for additional props that can be applied to this component.

prop	type	required	description	default
fullWidth	`boolean \| null`	false	Whether or not to have the Dropdown expand to fill its container's width	false