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.
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.
multiSelect is a boolean prop that if set to true will allow for multiple options to be selected from the Dropdown.
multiSelect is set to false by default.
multiSelect can also be used with the autocomplete functionality.
By default, the multiSelect prop will render selected options as the default FormPill. FormPillProps however can be used to customize these Pills with any props that exist for the FormPill.
This prop must be an object that contains valid FormPill props. For a full list of FormPill props, see here.
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.
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.
autocomplete prop can also be used in conjunction with the subcomponent structure.
The top-level Dropdown component optionally accepts any string through a label prop to produce a label above your trigger element.
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.
Optionally utilize customDisplay on the 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 customDisplay will display as the selected option.
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.
Optionally replace the default trigger's select element by passing child components directly to the Dropdown.Trigger.
The optional searchbar boolean prop can also be used on the 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.
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.
The activeStyle prop can be used to customize the appearance of the dropdown selection indicator. It accepts an object with the following keys: backgroundColor sets the background color of the selected item (and its hover state); fontColor sets the font color of the selected item.
backgroundColor Type: String | Values: bg_light | white | Default: (no selection) is primary
fontColor Type: String | Values: primary | all Playbook Text Colors | Default: (no selection) is white
Use the Dropdown.Option subcomponent structure to include custom layouts inside dropdown menus. Icons can be placed alongside the Body label text.
Radio inputs can be used inside Dropdown.Option for a custom layout that mimics form-like selection within a dropdown. Use the activeStyle backgroundColor and fontColor props to create contrast between the Radio selection indicator and the Dropdown selection background indicator.
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.
The useDropdown hook can also be used to toggle the dropdown open and closed using an external control. To do so, you must manage state with the custom hook, pass the dropdown:'pb-dropdown-trigger' data attribute to the external control and use the isClosed prop as shown.
