Some props/prop values deprecated in SWAN v3.3
Refer to the information on props/prop values provided further down this page. Find more information and migration documentation in the Deprecation roadmap.
Dropdown
A pull-down list of items that appear when the input is selected.
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.
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.
Line
skin="line" is deprecated in SWAN v3.3
Use the skin="standard" instead, which aligns with new semantic roles on SWAN components.
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.
Full width
Use fullWidth to grow a Dropdown to fill it's container.
With floating label
Use DropdownWithFloatingLabel to move the label inside the input. This creates visual harmony with other form elements like text inputs that support floating labels. Keep label text short or use the fullWidth prop to maximize width.
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.
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.
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.
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.
Don't...
- Use a Dropdown when listing fewer than 4 items. Use a single select Section Set instead, with radio buttons if space permits.
- 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 |
|---|---|---|---|---|
| size | "standard" | "mini" | null | false | ⚠️ Deprecated - This is deprecated without a replacement.
Mini will make the dropdown smaller | standard |
| 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 |
| fullWidth | boolean | null | false | whether or not the component should horizontally to fill its container's availableWidth | null |
| htmlSize | number | false | Specifies the number of visible options in a drop-down list. | 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 |
How does Dropdown meet your needs?
