Dropdown

A dropdown allows the user to select an option from a list of options in an expandable overlay.

Anatomy

1. Label - a short description or prompt that lets the user know what they will be selecting.
2. Button - a button that opens the dropdown listbox and displays the currently selected option.
   • Default text before selection should be "Select".
   • A marker should be displayed to the right of the button's text to convey whether the dropdown listbox is open or closed.
3. Listbox - a container for the list of options that only appears when opened by the dropdown button.
4. Options - the available options. Clicking an unselected option will select that option, deselect the currently selected option, and close the listbox.
5. Selected Option - the currently selected option.

Usage

• Use a dropdown to select one option from a collapsed set of available options.
• By default, dropdown options are mutually exclusive. The user can only select 1 option.
• When an option is selected, the dropdown closes and the selected option updates to display that item.
• On load, the dropdown should display default text of "Select". The user should be able to change it back to "Select" if they wish.
• Down Arrow/Up Arrow moves focus to the next/previous options, respectively.
• Home and End moves focus to the first/last options, respectively.

Do

• Do keep dropdown options very concise.
  • If long options are unavoidable, then they can truncate when the dropdown is in a closed state, but they should wrap fully in the open state.
• Do ensure that the clickable area includes the entire selected option area and the icon.
• Consider the most logical order to list options. Options could be listed alphabetically, chronologically, by popularity, etc.

Don't

• Do not start all of the options in a dropdown with the same word or phrase.
• If there are more than 6 options, consider using a combo box instead.
• If there are 2 options, consider using radio group or switch instead.
  • If your interface needs to contain many of these selections, use dropdowns over radio buttons.
• Do not use a dropdown when the user can multi-select options. Use checkboxes instead.
• If it is not absolutely necessary for a user to choose from a predefined set of options, then consider a text field for users to type their own information.

React API

We expose two components for the dropdown API: the Dropdown and the Option, which uses the BaseOption.

import { Dropdown, Option } from '@wwnds/react';

Dropdown

The Dropdown component does not expose a ref or extend a full DOM interface.

Live Editor

<Dropdown label="Choose a sitcom" sort="ascending">
	<Dropdown.Option>The Office</Dropdown.Option>
	<Dropdown.Option>Community</Dropdown.Option>
	<Dropdown.Option>Friends</Dropdown.Option>
	<Dropdown.Option>Parks and Recreation</Dropdown.Option>
	<Dropdown.Option>How I Met Your Mother</Dropdown.Option>
	<Dropdown.Option>Modern Family</Dropdown.Option>
	<Dropdown.Option disabled>The Big Bang Theory</Dropdown.Option>
	<Dropdown.Option>Arrested Development</Dropdown.Option>
</Dropdown>

Result

Loading...

Name	Description	Type
label (required)	The name of the dropdown. Required.	ReactNode
children (required)	The options for the listbox. Each will be rendered inside an Option component. When specifying an option as an OptionProps object, the option's value must be the OptionProps['children'].	(string | number | ReactElement<unknown, string | JSXElementConstructor<any>>)[]
sort	Sort options by value. undefined will leave the options unsorted.	"ascending" | "descending"
selected	A list of selected options.	string | number
buttonContents	The contents of the button. If specified, it will be used as the button contents. Otherwise, it will default to 'Select' on load and then it will match the contents of the currently selected option if no onChange callback is provided.	ReactNode
isOpen	Indicates whether the listbox is open.	boolean
closeOnExternalClick	Indicates whether clicking outside the listbox should close the listbox.	boolean
closeOnDocumentEscape	Indicates whether the dropdown should be closed on Escape.	boolean
matchWidth	Indicates that the button and listbox should match widths. button - the listbox will match the width of the button. listbox - the button will match the width of the listbox. undefined - no width matching should be done.	"button" | "listbox"
buttonWidth	Set the width of the button. Use when matchWidth="button" and the button's width is not set with CSS.	string | number
name	The name attribute for the internal <select>.	string
baseName	The base class name according to BEM conventions. Default is "dropdown".	string
labelClass	The class name for the label.	string
buttonClass	The class name for the button.	string
listboxClass	The class name for the listbox.	string
optionClass	The class name for all listbox options.	string
popperClass	The class name for the popper.	string
buttonId	An id for the button.	string
listboxId	An id for the listbox.	string
onRequestClose	Callback function that is called when the dropdown attempts to close its listbox. This will occur under the following conditions: The user clicks outside of the listbox and closeOnExternalClick is true. The user presses Escape and closeOnDocumentEscape is true. The user presses Tab while the listbox is open.	(() => void)
onRequestOpen	Callback function that is called when the dropdown attempts to open its listbox. This will occur under the following conditions: The user clicks the dropdown button (default: .dropdown__button). The user presses ArrowUp or ArrowDown while on the dropdown button.	(() => void)
onChange	Callback function that is called when an option is selected. This will occur under the following conditions: When the user clicks an option. When the user presses Enter on the currently focused option. When the user releases the space bar on the currently focused option.	((payload: { value: string | number; contents: ReactNode; }) => void)
autofocus	If set, the focusable dropdown option should be focused when it is rendered.	boolean
selectedMarker	Set the visual indicator for the selected option.	"dot" | "check"
description	An optional description. Use this in place of placeholder text or as help text for your field control.	ReactNode
descriptionClass	A className for the description <div>.	string
labelId	An id for the label element.	string
descriptionId	An id for the description <div>.	string
transition	The animation transition class applied to the popper as it enters or exits. A single name can be provided and it will be suffixed for each stage. For example, transition="fade" applies: fade-enter fade-enter-active fade-exit fade-exit-active fade-appear fade-appear-active Each individual stage can also be specified independently: transition={{ appear: 'my-appear', appearActive: 'my-appear-active', appearDone: 'my-appear-done', enter: 'my-enter', enterActive: 'my-enter-active', enterDone: 'my-enter-done', exit: 'my-exit', exitActive: 'my-exit-active', exitDone: 'my-exit-done' }} Reference: react-transition-group's CSSTransition.	string | CSSTransitionClassNames
distance	The offset distance (in pixels) from the reference. Will only be used if offset is undefined.	number
placement	The Floating UI placement option.	"auto" | Placement | "auto-start" | "auto-end"
modifiers	Legacy Popper modifier objects. Supported names: arrow, flip, offset, preventOverflow, and matchWidth.	{ name?: string; enabled?: boolean | undefined; options?: Record<string, unknown> | undefined; }[] | undefined
strategy	The Floating UI strategy option.	Strategy
onFirstUpdate	Called after the popper receives its first computed position while open.	((state: { elements: { popper: HTMLElement; reference: ReferenceElement; }; placement: Placement; }) => void)

Option

The Option component extends the React.ComponentPropsWithoutRef<'li'> interface, and uses the ARIA option role.

Note that the Dropdown also exposes the Option as a static member (Dropdown.Option) for your convenience.

Live Editor

<Option>Community</Option>

Result

Loading...

Name	Description	Type
disabled	If set, this option is not selectable.	boolean
label	The displayed option name. This will override children.	ReactNode
selected	Indicates that this option is currently selected.	boolean
value (required)	The value of the option that will be submitted. If undefined, the label or children will be used as the value.	string | number
marker	An element that comes before the label/children, similar to CSS ::marker. Defaults to a check mark, but can be set as a dot or a React element.	"dot" | ReactElement<unknown, string | JSXElementConstructor<any>> | "check"
optionClass		string