Yugen UI

Dropdown

Dropdown lets people pick one option from a custom listbox that opens below the field.

Unlike Select, the listbox is a custom surface (shadow-16, rounded-medium), so it supports a checkmark, groups with headings, disabled options and custom content. Keyboard: arrow keys, Home/End, type a character to jump, Enter to select, Esc to close. While the listbox is open, page scrolling is always locked; to keep the page scrollbar, see Scroll lock.

Import

Install from npm, copy the source into your project with @yugen-ui/cli or the shadcn CLI, or import directly when working in this repo.

TSX
// npm install yugen-uiimport { Dropdown, DropdownOption, DropdownGroup, DropdownDivider } from "yugen-ui";

Variants

Each tile is a standalone example: hover to copy, or press Code to see the source.

Groups & disabled options

DropdownGroup adds a heading; groups are separated by a divider automatically.

Selected: M

Controlled

value / onValueChange.

Options with icons

media places an icon before the label.

Appearance, size & disabled

Same appearance / size options as Input.

Usage

Do
  • Use an action placeholder (“Choose a department”) when there is no default value.
  • Group options with DropdownGroup when the list mixes several kinds of items.
  • Keep option labels short and clearly distinct.
Don't
  • Don't use it when there are only 2–3 options that should always be visible. Use RadioGroup.
  • Don't use it for very long lists without search. Use Combobox.
  • Don't put actions (commands) in a Dropdown. Use Menu.

Props

Prop · TypeDefaultDescription
placeholderReactNodeDefault: —Shown when nothing is selected.
value / defaultValuestringDefault: —Selected value (controlled / uncontrolled).
onValueChange(value: string) => voidDefault: —Called when an option is selected.
appearance"outline" | "underline" | "filled-darker" | "filled-lighter"Default: "outline"Trigger style.
size"small" | "medium" | "large"Default: "medium"Height 24 / 32 / 40px.
disabled, required, nameboolean / stringDefault: —Same as on a native form control.
className / listboxClassNamestringDefault: —Class for the trigger / the listbox surface.
DropdownOption.mediaReactNodeDefault: —Icon before the option label.
DropdownGroup.labelReactNodeDefault: —Group heading.