Option List

Open panel and option rows: search, checkboxes, secondary text, scroll, and footer actions.

Installation

Add this item from the registry, or import it from the package after installing Default File UI.

Registry path

itsvigneshv/default-file-ui/option-list

Package import

import { OptionList, OptionListContent, OptionListItem, OptionListSubmenu, OptionListSubContent } from "@default-file/ui/components/df-option-list"

Panel

The open list surface. Item rows are documented separately below.

Item states

List item alone: default, hover, selected (active), and disabled.

Item content

Leading checkbox, primary label, and muted secondary text across states.

Stacked description

Heading on top, description underneath. The whole block is one selectable option.

Stacked with checkbox

Same stacked layout with a leading checkbox for multi-select.

Trailing badge counter

Number counter at the end of the row via the trailing slot.

Groups and separators

Section labels and dividers inside the panel.

Search, scroll, and actions

Full panel chrome: search, scrollable body, and footer actions.

Properties

Open panel and option rows for pickers. Select composes this list for its menu.

OptionList

Root selection and open state.

Prop	Type	Default	Notes
selectionMode	"single" \| "multiple"	"single"	Single value or multiple values.
value	string \| null	—	Controlled value in single mode.
defaultValue	string \| null	null	Uncontrolled initial value in single mode.
onValueChange	(value: string \| null) => void	—	Called when the single value changes.
values	string[]	—	Controlled values in multiple mode.
defaultValues	string[]	[]	Uncontrolled initial values in multiple mode.
onValuesChange	(values: string[]) => void	—	Called when multiple values change.
open	boolean	—	Controlled open state.
defaultOpen	boolean	false	Uncontrolled initial open state.
onOpenChange	(open: boolean) => void	—	Called when the panel opens or closes.
closeOnSelect	boolean	—	Close after choosing a row. Defaults to true in single mode, false in multiple.
submenuAnimated	boolean	true	Default motion for all nested OptionListSubmenu panels. true plays open/close animations; false makes nested menus appear and disappear instantly. Overridden by OptionListSubmenu or OptionListSubContent animated.
submenuOpenDuration	number	180	Default open animation duration in milliseconds for nested submenus. Ignored when submenuAnimated is false. Overridden by OptionListSubmenu or OptionListSubContent openDuration.
submenuCloseDuration	number	90	Default close animation duration in milliseconds for nested submenus. Ignored when submenuAnimated is false. Overridden by OptionListSubmenu or OptionListSubContent closeDuration.

OptionListTrigger

Opens and closes the option list. Use render to compose onto Badge or another host.

Prop	Type	Default	Notes
render	ReactElement	—	Host element to clone trigger behavior onto (for example Badge). Owns click, keyboard, and anchor ref.
children	ReactNode	—	Trigger content (label, chevron, etc.).
className	string	—	Additional styles.
…button attributes	ButtonHTMLAttributes	—	Native button props when not using render.

OptionListContent

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

Prop	Type	Default	Notes
align	"start" \| "center" \| "end" \| "auto"	"start"	Horizontal anchor relative to the trigger. auto picks the best fit.
alignItemWithTrigger	boolean	false	When true, menu width matches the trigger. When false, the menu hugs option content (and stays at least as wide as the trigger).
side	"top" \| "bottom" \| "left" \| "right"	"bottom"	Preferred placement side.
sideOffset	number	4	Gap between trigger and panel.
alignOffset	number	0	Shift along the alignment axis.
portal	boolean	true	Render in a portal. Set false for inline previews.
search	boolean	false	Show a search field above the options.
searchPlaceholder	string	"Search"	Placeholder for the search field.
searchValue	string	—	Controlled search query.
defaultSearchValue	string	—	Uncontrolled initial search query.
onSearchChange	(value: string) => void	—	Called when the search query changes.
scrollable	boolean	false	Wrap options in a scroll area.
scrollMaxHeight	string \| number	"16rem"	Max height of the scrollable body.
footer	ReactNode	—	Footer actions under the options (for example Reset).
className	string	—	Panel surface styles.

OptionListItem

Selectable row with leading control, secondary copy, trailing badge or chevron, and selection indicator. Inside OptionListSubmenu (trigger zone) it opens the submenu on hover instead of selecting.

Prop	Type	Default	Notes
value	string	—	Option value stored in selection state.
disabled	boolean	—	Non-selectable row.
leading	"checkbox" \| "check" \| ReactNode \| false	—	Leading control. Use "checkbox" for multi-select rows.
secondary	ReactNode	—	Supporting copy beside or under the label.
layout	"inline" \| "stacked"	"inline"	inline places secondary beside the label; stacked places it underneath.
trailing	ReactNode	—	End-of-row slot: badge counter, nested-menu chevron, or both. When set, the selected check is hidden unless indicator is forced on.
indicator	boolean	—	Selected check in single mode. Defaults off when leading is checkbox or trailing is set; otherwise on.
children	ReactNode	—	Primary label text for the row.
className	string	—	Additional row styles.
…div attributes	HTMLAttributes	—	Native div props. Use data-highlighted for hover/open parent rows in nested menus.

OptionListSubmenu

Hover-open nested branch. Wrap a trigger OptionListItem and an OptionListSubContent. Nest again inside the content for deeper levels. Motion defaults inherit from OptionList and can be overridden here.

Prop	Type	Default	Notes
open	boolean	—	Controlled submenu open state.
defaultOpen	boolean	false	Uncontrolled initial open state (useful for docs previews).
onOpenChange	(open: boolean) => void	—	Called when the submenu opens or closes.
animated	boolean	inherits OptionList.submenuAnimated (true)	true plays fade/slide open and close for this branch. false opens and closes instantly with no motion. Prefer OptionList submenuAnimated=false to turn off motion for every nested level at once.
openDuration	number	inherits OptionList.submenuOpenDuration (180)	Open animation duration in milliseconds for this branch. Only applies when animated is true.
closeDuration	number	inherits OptionList.submenuCloseDuration (90)	Close animation duration in milliseconds for this branch. Only applies when animated is true. Keep this shorter than openDuration for a snappy dismiss.
closeDelay	number	60	Milliseconds to wait after the pointer leaves the branch before starting close. Gives time to move into the child panel. Exit animation (if animated) starts after this delay.
children	ReactNode	—	Trigger OptionListItem plus OptionListSubContent (and nested submenus).

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.

Prop	Type	Default	Notes
side	"top" \| "bottom" \| "left" \| "right"	"right"	Preferred placement relative to the parent row.
sideOffset	number	4	Gap between the parent row and the child panel.
align	"start" \| "center" \| "end" \| "auto"	"start"	Alignment along the parent row.
alignOffset	number	0	Shift along the alignment axis.
portal	boolean	true	Render in a portal. Set false for inline nested previews in docs.
animated	boolean	inherits OptionListSubmenu.animated	Per-panel motion override. false makes this panel appear and disappear instantly even if parent submenus are animated.
openDuration	number	inherits OptionListSubmenu.openDuration	Per-panel open duration in milliseconds. Ignored when animated is false.
closeDuration	number	inherits OptionListSubmenu.closeDuration	Per-panel close duration in milliseconds. Ignored when animated is false.
className	string	—	Panel surface styles.
children	ReactNode	—	Option rows and nested OptionListSubmenu branches.

OptionListSearch

Search field used when content search is composed manually.

Prop	Type	Default	Notes
placeholder	string	"Search"	Empty-state hint.
value	string	—	Controlled query.
defaultValue	string	—	Uncontrolled initial query.
onValueChange	(value: string) => void	—	Called when the query changes.
size	"sm" \| "md" \| "lg"	"sm"	SearchInput size.
clearable	boolean	true	Show clear control when filled.

OptionListBody

Scrollable or static body wrapping option rows.

Prop	Type	Default	Notes
scrollable	boolean	false	Wrap children in ScrollArea.
maxHeight	string \| number	"16rem"	Height constraint when scrollable.
children	ReactNode	—	Option rows.

OptionListFooter

Prop	Type	Default	Notes
children	ReactNode	—	Footer actions (for example Reset / Select all).
className	string	—	Additional styles.

Grouping parts

Prop	Type	Default	Notes
OptionListGroup	div attrs	—	Groups related items.
OptionListLabel	div attrs	—	Muted group heading inside the panel.
OptionListSeparator	separator	—	Horizontal rule between sections.
OptionListScrollUpButton / ScrollDownButton	button	—	Optional scroll affordances for long lists.
useOptionListContext	() => context	—	Read open state, selection, labels, and search from parts.

Layout & appearance

Prop	Type	Default	Notes
Hug content	alignItemWithTrigger={false}	false	Panel width follows option content; at least trigger width.
Match trigger width	alignItemWithTrigger	—	Lock panel width to the trigger.
Inline previews	portal={false}	—	Render the panel in place for docs and nested layouts.
Trailing badge counter	trailing={<Badge>…</Badge>}	—	Number badge at the end of the row. Right padding matches checkbox rows; selected check stays hidden.
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 + ChevronRight. 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.