Default


This kit's options prop requires an array of objects, each of which will be used as the selectable options within the dropdown. Each option object can support any number of key-value pairs, but each must contain label and value.

Subtle Variant


For the subtle variant, it is recommended that you set the Separators prop to false to remove the separator lines between the options for a more cleaner look.

Subcomponent Structure


The dropdown is built using all of the following subcomponents:

Dropdown.Trigger is the UI component that users interact with to toggle the dropdown.
Dropdown.Container is the floating container that wraps the list of dropdown options.
Dropdown.Option renders options that are passed to the container.
Each of these subcomponents can be altered using global props and/or their respective props. See doc examples below for more information on each.

With Label


The top-level Dropdown component optionally accepts any string through a label prop to produce a label above your trigger element.

Custom Options


Dropdown.Option subcomponent accepts any child components to customize the options' contents and display. By default, options are Body kit text that is set by the label value from the option object.

Custom Display


Optionally utilize customDisplay on the Dropdown.Trigger subcomponent to customize its content after an option is selected. The component passed to customDisplay will be rendered to the left of the default text-based display. In this example the Avatar kit is being used.

The placeholder prop can also be used to customize the placeholder text for the default Dropdown.Trigger.

The onSelect prop returns the selected option as an object to be utilized by the dev. In this example we are using the onSelect to set a state with the selected option and using it to customize the customDisplay.

Custom Trigger


Optionally replace the default trigger's select element by passing child components directly to the Dropdown.Trigger.

Custom Option Padding


By default, dropdown option paddingX is set to sm and paddingY is set to xs, but this padding can be overridden using our global padding props. In this example we are setting the option padding to sm all around.

Dropdown with Error


Default Value


Blank Selection


Clear Selection


To use an external control (like a reset button) to clear Dropdown selection, you can make use of the useRef hook. You must pass a ref to the Dropdown component and use that ref within the onClick for the external control in the way shown in the code snippet below.

Separators Hidden



Available Props