Option List

OptionList

Root selection, open state, and width.

OptionListTrigger

Opens and closes the option list. Use render to compose onto List Item, Badge, or another host. When OptionList width is fill or fixed, the render host stretches to that width so List Item trailing slots stay end-aligned.

OptionListContent

Portaled or inline panel with optional header, search, scroll, footer, and dismissOnScroll.

OptionListItem

Selectable List Item with value, search filter, and submenu trigger behavior. Forwards List Item presentation props (size, variant, leading, trailing, layout, and full chrome: padding, type, fills, stroke, radius). Selection, highlight, and open state stay owned by Option List. Nested submenu triggers pass ListItemSubmenuChevron (or Badge plus that chevron) through trailing. Inside OptionListSubmenu (trigger zone) the row opens the submenu on hover instead of selecting. For standalone rows and asChild links, see List Item.

OptionListSubmenu

Hover open nested branch. Wrap a trigger OptionListItem and an OptionListSubContent. The trigger is a normal OptionListItem, so List Item size, variant, trailing chevron, and chrome props apply. Nest again inside the content for deeper levels. Motion defaults inherit from OptionList and can be overridden here.

OptionListSubContent

Child panel for a submenu. Opens on hover of the parent row; nest further OptionListSubmenu trees inside. Placement and motion can be set per panel.

OptionListSearch

Search field used when content search is composed manually.

OptionListBody

Scrollable or static body wrapping option rows.

OptionListHeader

Panel title block with an edge-to-edge bottom rule. Distinct from OptionListLabel, which is an in-list group heading.

OptionListFooter

OptionListGroup

Groups related items.

OptionListLabel

Group heading inside the panel. Renders ListItemLabel with variant menu.

OptionListSeparator

Horizontal rule between in-list sections. For a panel header rule that touches both edges, use OptionListHeader.

OptionListScrollUpButton and OptionListScrollDownButton

Optional scroll affordances for long lists.

useOptionListContext

Hook for composed parts. Returns open state, selection, labels, and search from the nearest OptionList.

Layout and appearance

Fixed width (width CSS length): Pass a CSS length on OptionList such as 12rem or 200px. Sets --df-option-list-width on the root. Hug menu content (alignItemWithTrigger={false}): Open menu width follows option content. Default when root width is hug, or pass false to override fill and fixed. Match trigger width (alignItemWithTrigger): Lock open menu width to the trigger. Default when root width is fill or fixed. Inline previews (portal={false}): Render the panel in place for docs and nested layouts. Trailing badge counter (trailing={<Badge>}): Number badge at the end of the row. Right padding matches checkbox rows; selected check stays hidden. Hover flyout (openOnHover): Open the root panel from a trigger on pointer enter. Keep the pointer over the trigger, panel, or nested submenu panels to stay open. Click, Enter, and Space open when closed without toggle-close. Compose OptionListTrigger onto List Item for sidebar and rail rows. Set width fill so the trigger row spans the rail and trailing icons stay end-aligned. Nested submenu row (OptionListSubmenu + SubContent): Hover the parent row to open the child panel on the right. Nest Submenu trees for three or more levels. Use trailing for Badge plus ListItemSubmenuChevron. Control motion with submenuAnimated / animated (boolean) and submenuOpenDuration / submenuCloseDuration or openDuration / closeDuration (ms). Instant nested menus (submenuAnimated={false}): Disable open/close animation for every nested level from OptionList. Equivalent per branch: OptionListSubmenu animated={false}. Custom nested speed (submenuOpenDuration / submenuCloseDuration): Set open and close durations in milliseconds on OptionList (defaults 180 / 90). Override on a single Submenu or SubContent when one branch should feel different. Item spacing (CSS): Rows use kit gap and hover/selected/disabled states via data attributes. List Item props (ListItem): OptionListItem and submenu trigger rows render List Item. size, variant, slots, and chrome props forward through. Open and selected appearance are controlled by Option List. Open the List Item page for the full contract and standalone use.

Keyboard and accessibility

Applies to portaled panels. Inline panels (portal={false}) keep the page focus flow unchanged. Open and focus (built-in): Opening moves focus into the panel, or the search field when one is present. Closing by keyboard or selection returns focus to the trigger. Arrow keys (ArrowUp / ArrowDown): Move the active option with wrap around the ends. Home and End jump to the first and last option. Select (Enter / Space): Enter selects the active option. Space selects when focus is on the panel; inside the search field Space types a space. Typeahead (printable keys): Jump to the first option that starts with the typed query, then to any option that contains it. The buffer clears after a short pause. Disabled while a search field is present. Submenus (ArrowRight): Opens the submenu when the active row is a submenu trigger. ARIA (listbox): The panel is a listbox with aria-activedescendant on the active option. When OptionListHeader has a label, the listbox uses aria-labelledby. The trigger exposes aria-controls to the panel while open. High contrast (forced-colors): Under forced-colors, selected and active rows use the system Highlight and HighlightText colors.

Tokens

Theme defaults live on :root. Override these globally or on a local host.