@acusti/dropdown
Dropdown
is a React component that renders a menu-like UI with a trigger
that the user clicks to disclose a dropdown positioned below the trigger.
The body of the dropdown can include any DOM, and many dropdowns can be
combined to form a multi-item menu, like the system menu in the top toolbar
of macOS.
The three primary design goals for the existence of this component:
- Best-in-class UX (inspired by macOS native menus) with excellent
keyboard support
- Best-in-class DX with the simplest possible API:
- To create a dropdown with a
<button>
trigger, pass in a single
child element with the body of the dropdown - To create a dropdown with a custom trigger, pass in exactly two
child elements; the first is the trigger, the second is the body of
the dropdown
- To create a dropdown with a list of items as the body, use the
data-ukt-item
boolean to mark dropdown items, or use
data-ukt-value="foo"
to specify that an element is a dropdown item
and the value of that item at the same time (otherwise, the value is
the text content of the dropdown item element) - To style your dropdowns, use CSS; there are a
collection of CSS custom properties
used internally to style them if that works best for you, or just
override the minimal default CSS as appropriate
- Lightweight bundle size with the bare minimum of dependencies (see
minzipped size above)
See the storybook docs and demo to get a feel for what it can do.
Usage
npm install @acusti/dropdown
# or
yarn add @acusti/dropdown
Props
This is the type signature for the props you can pass to Dropdown
. The
unique features provided by the component are called out and explained
above the corresponding prop via JSDoc comments:
type Props = {
allowCreate?: boolean;
allowEmpty?: boolean;
className?: string;
disabled?: boolean;
hasItems?: boolean;
isOpenOnMount?: boolean;
isSearchable?: boolean;
keepOpenOnSubmit?: boolean;
label?: string;
name?: string;
onClick?: (event: React.MouseEvent<HTMLElement>) => unknown;
onClose?: () => unknown;
onMouseDown?: (event: React.MouseEvent<HTMLElement>) => unknown;
onMouseUp?: (event: React.MouseEvent<HTMLElement>) => unknown;
onOpen?: () => unknown;
onSubmitItem?: (payload: Item) => void;
placeholder?: string;
style?: React.CSSProperties;
tabIndex?: number;
value?: string;
};