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.
The blankSelection prop adds a blank option at the top of the dropdown options list. This allows users to explicitly clear their selection by choosing the blank option.
The blank selection option appears as the first item in the dropdown and has an empty value (id: "", value: ""). When selected, it effectively clears the dropdown selection.
The placeholder prop allows you to customize the placeholder text that appears when no option is selected in the dropdown.
The placeholder prop works with all dropdown variants (default, subtle, and quickpick). When no option is selected, the placeholder text is displayed. When an option is selected, the placeholder is replaced by the selected option's label. The default placeholder text is "Select..." if no placeholder is provided.
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 clearable prop controls whether the clear (X) button appears in the dropdown. When set to false, the clear button is hidden.
This is useful in two scenarios:
The constrainHeight prop limits the dropdown container height to 18em and enables vertical scrolling when the content exceeds this height. This prevents long dropdown lists from rendering off-screen.
When constrainHeight is true, the dropdown will:
This is particularly useful for dropdowns with many options, such as long lists or quickpick variants with many date range options.
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.
The QuickPick variant provides predefined date based options when variant="quickpick" is used.
Open the Dropdown above to see the default options.
The optional rangeEndsToday prop can be used with the quickpick variant to set end date on all ranges that start with 'this' to today's date. For instance, by default 'This Year' will set end day to 12/31/(current year), but if rangeEndsToday prop is used, end date on that range will be today's date.
To set a default value for the Dropdown, you can use the label of the range you want set as default, for example "This Year", "Today", etc.
The customQuickPickDates prop allows for defining custom quick pick date options for the dropdown. The prop accepts an object with two properties: dates and override.
The dates property accepts an array of objects. Each object has label and value properties. The label is what will be displayed in the dropdown menu. The value property defines the date range that will be selected, and can be:
["06/01/2022", "06/07/2022"])timePeriod and amount properties for dynamic date calculations:
timePeriod property accepts "days", "weeks", "months", "quarters", or "years", representing past time periods calculated from today.amount property accepts any number.The override property is a boolean that controls whether custom dates replace or append to the default quick pick options. Default is true (replaces defaults). Set to false to append your custom dates to the default quick pick options.
You can link a Dropdown (quickpick variant) to standard DatePickers using the following props:
For the Dropdown:
controlsStartId: ID of the DatePicker that should receive the start date.
controlsEndId: ID of the DatePicker that should receive the end date.
When a quickpick option like “This Year” is selected, it automatically populates the linked start and end inputs.
For the Start/End DatePickers:
syncStartWith: ID of the quickpick this start date is synced to.
syncEndWith: ID of the quickpick this end date is synced to.
When a user manually edits the start or end date, it clears the selected quickpick to prevent conflicting values.
