Playbook logo
14.19.0
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.

Autocomplete


The autocomplete prop can be used to add autocomplete or typeahead functionality to the Dropdown's default Trigger. This prop is set to 'false' by default.

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 cleaner look.

Subcomponent Structure


The dropdown is built using all of the following required subcomponents:

dropdown/dropdown_trigger is the UI component that users interact with to toggle the dropdown.
dropdown/dropdown_container is the floating container that wraps the list of dropdown options.
dropdown/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.

Autocomplete with Subcomponent Structure


autocomplete prop can also be used in conjunction with the subcomponent structure.

With Label

Select a Country

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

Custom Options


dropdown/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 custom_display on the dropdown/dropdown_trigger subcomponent to customize its content after an option is selected. Pass in any combination of kits to create a custom display. When a user clicks on an option, the kits passed into custom_display will display as the selected option.

Make use of a script to help set the custom_display with the correct value. By using the pb:dropdown:selected event listener, you can target the kits with a querySelector and update them dynamically with the values needed to match the selected option. Make sure to add an ID to the kits being passed in.

The placeholder prop can also be used to customize the placeholder text for the default dropdown/dropdown_trigger.

The dropdown follows the typical rails pattern of utilizing hidden inputs for form submission. The hidden input value is the selected options' id.

Custom Trigger


Optionally replace the default trigger's select element by passing child components directly to the dropdown/dropdown_trigger.



The optional searchbar boolean prop can also be used on the dropdown/dropdown_container to render a searchbar with typeahead functionality within the dropdown itself. This is especially useful when a custom trigger is being used.
searchbar is set to false by default.

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.



Default Value


Blank Selection


Separators Hidden




Available Props

Props Type Values Default

options

array

label

string

name

string

error

string

required

boolean
false

default_value

string

blank_selection

string

variant

enum
default
subtle
default

separators

boolean
true

autocomplete

boolean
false

searchbar

boolean
false