Dropdown
Dropdowns are compact UI controls that allow users to select an option, require a click to see options, and support only single-selection.
Behavior
Installation
yarn add @vtex/admin-ui
import { Dropdown, useDropdownState } from '@vtex/admin-ui'
Variations
Variant
In the same way as the buttons, the variant prop represents the appearance of the Dropdown, indicating whether it is a solid (default), soft, or a text action.
Items
Dropdown items can be a List of either native types (like number, string, etc.), or Object types. Check the examples below to see how to handle these two different approaches.
String
When using a String to represent the item, the dropdown already knows what it should render in the options, so you just need to specify the items property to both useDropdownState and Dropdown.
Object
When using an Object to represent the item there are two things that you should do:
Define the itemToString prop in the useDropdownState. It will return the string equivalent of the item which will be used for selection/highlight by character keys and for the aria-live a11y selection message that will occur on every item selection: "$ItemString has been selected". In the example below, we use the item.label to be the string equivalent of each item object.
Define the renderItem prop in the Dropdown. It is similar to the itemToString and will return the string equivalent of each item in the select menu.
Disabled
It means that the user will not be able to select any value from the Dropdown. To use this variation, the disabled property should have a true value.
State
useDropdownState
Hook that manages all the stateful logic needed to make the select functional and accessible. It returns a set of props that are meant to be called, and their results are destructured on the dropdown's elements: its label, toggle button, list, and list items.
It is the same as the Downshift useSelect Hook.
Customization
You can use the csx property to customize any style.
Example
Props
| Name | Type | Description | Required | Default |
|---|---|---|---|---|
| state | DropdownState | Return of useDropdownState | ✅ | - |
| label | string | Label | ✅ | - |
| items | T[] | List of dropdown items | ✅ | - |
| renderItem | (item: T or null) => ReactNode | Function that defines whats rendered for each item | 🚫 | (item) => item |