This library is still in development and is available only for internal usage at VTEX.
Skip to main content

Dropdown

Version: 0.134.0

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

Loading...

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.

Loading...

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.

Loading...

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.

Loading...

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.

Loading...

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.

Loading...

Customization

You can use the csx property to customize any style.

Example

Loading...

Props

NameTypeDescriptionRequiredDefault
stateDropdownStateReturn of useDropdownState-
labelstringLabel-
itemsT[]List of dropdown items-
renderItem(item: T or null) => ReactNodeFunction that defines whats rendered for each item🚫(item) => item