# DropdownMenu > A value picker with a button trigger and a list of options. Source: /docs/components/dropdown-menu ```tsx import { DropdownMenu } from '@aksornproject/aksara-ui' ``` For a labelled form field, use [Select](/docs/components/select). To run actions, use [Menu](/docs/components/menu). ## Sort picker `DropdownMenu` has 11 parts. `DropdownMenu.Root` is `Select.Root`. `DropdownMenu.Button` is a library `Button` that shows `leadingText`, the selected value and a `trailingNode` that swaps between its `open` and `closed` nodes. `DropdownMenu.List` is the portal, positioner, popup and list in one part. The popup is at least 230px wide and at most 256px tall, with a border and a 10px radius. A selected item shows a 24px accent tick. `selectedIndicator` replaces the tick, and an empty fragment hides it. ```tsx import { IconInterfaceEssentialArrow, IconInterfaceEssentialArrow1, } from '@aksornproject/aksara-icons' import { DropdownMenu } from '@aksornproject/aksara-ui' import { useState } from 'react' type Sort = 'newest' | 'oldest' | 'name' const options: { value: Sort; label: string }[] = [ { value: 'newest', label: 'Newest' }, { value: 'oldest', label: 'Oldest' }, { value: 'name', label: 'Name' }, ] export default function DropdownMenuSort() { const [sort, setSort] = useState('newest') return ( , closed: , }} className="w-[216px]" /> {options.map((item) => ( setSort(item.value)} > {item.label} ))} ) } ``` ## With Select This is the same sort picker built with `Select`. `Select.Trigger` puts the label above the field, and the popup is at least 280px wide. For a list of actions, use `Menu`, whose items are announced as `menuitem` rather than `option`. ```tsx import { Select } from '@aksornproject/aksara-ui' import { useState } from 'react' type Sort = 'newest' | 'oldest' | 'name' const options: { value: Sort; label: string }[] = [ { value: 'newest', label: 'Newest' }, { value: 'oldest', label: 'Oldest' }, { value: 'name', label: 'Name' }, ] export default function DropdownMenuSelect() { const [sort, setSort] = useState('newest') return (
value && setSort(value)} > {options.map((item) => ( {item.label} ))}
) } ``` ## Accessibility - `DropdownMenu.Button` is one native button with `role="combobox"`. Its default `type` is `button`, so opening it inside a form does not submit the form. - A `DropdownMenu.Trigger` with a library `Button` child makes that button the trigger, so buttons do not nest. - The popup is a `listbox` of `option`s. An action menu built on it announces values, not actions. Use `Menu` for actions. - Arrow keys reach disabled items, but Enter and clicks do not select them. ## API ### DropdownMenu.Root `DropdownMenu.Root` is `Select.Root`. | Prop | Type | Default | Description | | --- | --- | --- | --- | | `children` | `ReactNode` | | | | `inputRef` | `React.Ref` | | A ref to access the hidden input element. | | `name` | `string` | | Identifies the field when a form is submitted. | | `form` | `string` | | Identifies the form that owns the hidden input. Useful when the select is rendered outside the form. | | `autoComplete` | `string` | | Provides a hint to the browser for autofill. | | `id` | `string` | | The id of the Select. | | `required` | `boolean` | `false` | Whether the user must choose a value before submitting a form. | | `readOnly` | `boolean` | `false` | Whether the user should be unable to choose a different option from the select popup. | | `disabled` | `boolean` | `false` | Whether the component should ignore user interaction. | | `multiple` | `Multiple` | `false` | Whether multiple items can be selected. | | `highlightItemOnHover` | `boolean` | `true` | Whether moving the pointer over items should highlight them. Disabling this prop allows CSS `:hover` to be differentiated from the `:focus` (`data-highlighted`) state. | | `defaultOpen` | `boolean` | `false` | Whether the select popup is initially open. To render a controlled select popup, use the `open` prop instead. | | `onOpenChange` | `((open: boolean, eventDetails: SelectRootOpenChangeEventDetails) => void)` | | Event handler called when the select popup is opened or closed. | | `onOpenChangeComplete` | `((open: boolean) => void)` | | Event handler called after any animations complete when the select popup is opened or closed. | | `open` | `boolean` | | Whether the select popup is currently open. | | `modal` | `boolean` | `true` | Determines if the select enters a modal state when open. - `true`: user interaction is limited to the select: document page scroll is locked and pointer interactions on outside elements are disabled. - `false`: user interaction with the rest of the document is allowed. On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior. | | `actionsRef` | `React.RefObject` | | A ref to imperative actions. - `unmount`: Ends the closing phase of the select after an externally controlled closing animation finishes. Call `preventUnmountOnClose()` in `onOpenChange` first, otherwise the select completes closing on its own. Whether it leaves the DOM is decided by `keepMounted` on the portal. - `close`: Closes the select imperatively when called. | | `items` | `readonly Group[] \| readonly { label: React.ReactNode; value: any; }[] \| Record` | | Data structure of the items rendered in the select popup. When specified, `` renders the label of the selected item instead of the raw value. | | `itemToStringLabel` | `((itemValue: Value) => string)` | | When the item values are objects (``), this function converts the object value to a string representation for display in the trigger. If the shape of the object is `{ value, label }`, the label will be used automatically without needing to specify this prop. | | `itemToStringValue` | `((itemValue: Value) => string)` | | When the item values are objects (``), this function converts the object value to a string representation for form submission. If the shape of the object is `{ value, label }`, the value will be used automatically without needing to specify this prop. | | `isItemEqualToValue` | `((itemValue: Value, value: Value) => boolean)` | | Custom comparison logic used to determine if a select item value matches the current selected value. Useful when item values are objects without matching referentially. Defaults to `Object.is` comparison. | | `defaultValue` | `SelectInputValue \| null` | | The uncontrolled value of the select when it's initially rendered. To render a controlled select, use the `value` prop instead. | | `value` | `SelectInputValue \| null` | | The value of the select. Use when controlled. | | `onValueChange` | `((value: SelectOutputValue \| (Multiple extends true ? never : null), eventDetails: SelectRootChangeEventDetails) => void)` | | Event handler called when the value of the select changes. | | `loading` | `boolean` | | Shows the skeleton bar in the trigger. The popup does not open and the value cannot change. The trigger stays focusable. | ### DropdownMenu.Button A library `Button`, `size="lg"` by default, that takes every `Button` prop and these two. Its children are ignored. Its event handlers run before the Base UI handlers. `disabled` stops it opening. | Prop | Type | Default | | -------------- | ---------------------------------------- | -------- | | `leadingText` | `string` | required | | `trailingNode` | `{ open: ReactNode; closed: ReactNode }` | none | | Prop | Type | Description | | --- | --- | --- | | `color` | `"brand" \| "destructive" \| "information" \| "sub-brand" \| "success" \| "warning"` | | | `variant` | `"link" \| "link-accent" \| "link-brand" \| "primary" \| "secondary" \| "secondary-accent" \| "secondary-brand" \| "tertiary" \| "tertiary-accent" \| "tertiary-brand" \| "tertiary-inverted"` | | | `leadingIcon` | `ReactNode` | | | `trailingIcon` | `ReactNode` | | | `size` | `"huge" \| "lg" \| "md" \| "sm" \| "xl" \| "xs"` | | | `iconOnly` | `boolean` | Renders a square button. A `leadingIcon` replaces the children; without one, the children render inside the icon box. `trailingIcon` still renders. | | `wrapperClasses` | `{ leadingIcon?: string; trailingIcon?: string; iconOnlyChildren?: string; }` | | | `forceFocusVisible` | `boolean` | Shows the focus ring without keyboard focus, for example while a menu opened by this button is open. | | `loading` | `boolean` | Hides the label, keeps the width, and shows three dots. The button is `aria-disabled` and stays focusable. Click, key, and pointer handlers do not run, including those on a `render` element. | | `render` | `ComponentRenderFn \| React.ReactElement>` | Replaces the rendered element. See Base UI `render`. | | `nativeButton` | `boolean` | Set to `false` when `render` returns an element other than `