Select

In Nyte

import { Select } from "@nyte-ai/ui/select";

@nyte-ai/ui/select re-exports the Base UI namespace unchanged. There is no Nyte styling on this subpath; the consumer owns every class, StyleX style, and layout decision. Base UI owns the interaction model, keyboard handling, focus management, and ARIA below.

Consumed by:

• desktop/src/renderer/src/chrome/settings-controls.tsx

The rest of this page is Base UI's documentation for @base-ui/react/select, reproduced verbatim under the MIT license, © Material-UI SAS. Component paths in examples refer to the Base UI package; in Nyte, import from the subpath above.

Usage guidelines

• Prefer Combobox for large lists: Select is not filterable, aside from basic keyboard typeahead functionality to find items by focusing and highlighting them. Prefer Combobox instead of Select when the number of items is sufficiently large to warrant filtering.
• Special positioning behavior: The select popup by default overlaps its trigger so the selected item's text is aligned with the trigger's value text. This behavior can be disabled or customized.
• Form controls must have an accessible name: Prefer <Select.Label>, or provide an aria-label on <Select.Trigger> when no visible label is rendered. See Labeling a select and the forms guide.

Anatomy

Import the component and assemble its parts:

import { Select } from '@base-ui/react/select';

<Select.Root>
  <Select.Label />
  <Select.Trigger>
    <Select.Value />
    <Select.Icon />
  </Select.Trigger>

  <Select.Portal>
    <Select.Backdrop />
    <Select.Positioner>
      <Select.Popup>
        <Select.ScrollUpArrow />
        <Select.Arrow />
        <Select.List>
          <Select.Item>
            <Select.ItemText />
            <Select.ItemIndicator />
          </Select.Item>
          <Select.Separator />
          <Select.Group>
            <Select.GroupLabel />
          </Select.Group>
        </Select.List>
        <Select.ScrollDownArrow />
      </Select.Popup>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>;

Positioning

<Select.Positioner> has a special prop called alignItemWithTrigger which causes the positioning to act differently by default from other Positioner components. The prop makes the select popup overlap the trigger so the selected item's text is aligned with the trigger's value text.

For styling, data-side is "none" on the .Popup and .Positioner parts when the mode is active.

To prevent the select popup from overlapping its trigger, set the alignItemWithTrigger prop to false. When set to true (its default) there are a few important points to note about its behavior:

• Interaction type dependent: For UX reasons, the alignItemWithTrigger positioning mode is disabled if touch was the pointer type used to open the popup.
• Viewport space dependent: There must be enough space in the viewport to align the selected item's text with the trigger's value text without causing the popup to be too vertically small - otherwise, it falls back to the default positioning mode. This can be customized by setting min-height on the <Select.Positioner> element; a smaller value will fallback less often. Additionally, the trigger must be at least 20px from the edges of the top and bottom of the viewport, or it will also fall back.
• Other positioning props are ignored: Props like side or align have no effect unless the prop is set to false or when in fallback mode.

Examples

Typed wrapper component

The following example shows a typed wrapper around the Select component with correct type inference and type safety:

import * as React from 'react';
import { Select } from '@base-ui/react/select';

export function MySelect<Value, Multiple extends boolean | undefined = false>(
  props: Select.Root.Props<Value, Multiple>,
): React.JSX.Element {
  return <Select.Root {...props}>{/* ... */}</Select.Root>;
}

Formatting the value

By default, the <Select.Value> component renders the raw value.

Passing the items prop to <Select.Root> instead renders the matching label for the rendered value:

// @highlight-text "items"
const items = [
  { value: null, label: 'Select theme' },
  { value: 'system', label: 'System default' },
  { value: 'light', label: 'Light' },
  { value: 'dark', label: 'Dark' },
];

// @highlight-text "items"
<Select.Root items={items}>
  <Select.Value />
</Select.Root>;

A function can also be passed as the children prop of <Select.Value> to render a formatted value:

const items = {
  monospace: 'Monospace',
  serif: 'Serif',
  'san-serif': 'Sans-serif',
};

<Select.Value>
  {/* @highlight-start */}
  {(value: keyof typeof items) => (
    <span style={{ fontFamily: value }}>
      {items[value]}
    </span>
  )}
  {/* @highlight-end */}
</Select.Value>;

To avoid lookup, object values for each item can also be used.

Labeling a select

Use <Select.Label> to provide a visible label for the select trigger:

<Select.Root>
  {/* @highlight */}
  <Select.Label>Theme</Select.Label>
  {/* ... */}
</Select.Root>

<Select.Label> renders a <div>, so clicking it focuses the select trigger without opening the popup.

Placeholder values

To show a placeholder value, use the placeholder prop on <Select.Value>:

const items = [
  { value: 'system', label: 'System default' },
  { value: 'light', label: 'Light' },
  { value: 'dark', label: 'Dark' },
];

<Select.Root items={items}>
  {/* @highlight */}
  <Select.Value placeholder="Select theme" />
</Select.Root>;

With placeholders, users cannot clear selected values using the select itself. If the select value should be clearable from the popup (instead of an external "reset" button), use a null item rendered in the list itself:

const items = [
  // @highlight
  { value: null, label: 'Select theme' },
  { value: 'system', label: 'System default' },
  { value: 'light', label: 'Light' },
  { value: 'dark', label: 'Dark' },
];

<Select.Root items={items}>
  <Select.Value />
</Select.Root>;

Multiple selection

Add the multiple prop to the <Select.Root> component to allow multiple selections.

Object values

Select items can use objects as values instead of primitives. This lets you access the full object in custom render functions, and can avoid needing to specify items for lookup.

Grouped

Organize related options with <Select.Group> and <Select.GroupLabel> to add section headings inside the popup.

Groups are represented by an array of objects with an items property, which itself is an array of individual items for each group. An extra property, such as value, can be provided for the heading text when rendering the group label.

interface ProduceGroupItem {
  value: string;
  // @highlight
  items: string[];
}

const groups: ProduceGroupItem[] = [
  {
    value: 'Fruits',
    // @highlight
    items: ['Apple', 'Banana', 'Orange'],
  },
  {
    value: 'Vegetables',
    // @highlight
    items: ['Carrot', 'Lettuce', 'Spinach'],
  },
];

API reference

Root

Groups all parts of the select. Doesn't render its own HTML element.

Root Props:

items Prop Example:

const items = {
  sans: 'Sans-serif',
  serif: 'Serif',
  mono: 'Monospace',
  cursive: 'Cursive',
};
<Select.Root items={items} />;

autoComplete Prop References:

• See developer.mozilla.org

Root.Props

Re-export of Root props.

Root.State

type SelectRootState = {};

Root.Actions

type SelectRootActions = { unmount: () => void };

Root.ChangeEventReason

type SelectRootChangeEventReason =
  | 'trigger-press'
  | 'outside-press'
  | 'escape-key'
  | 'window-resize'
  | 'item-press'
  | 'focus-out'
  | 'list-navigation'
  | 'cancel-open'
  | 'none';

Root.ChangeEventDetails

type SelectRootChangeEventDetails = (
  | { reason: 'trigger-press'; event: MouseEvent | PointerEvent | TouchEvent | KeyboardEvent }
  | { reason: 'outside-press'; event: MouseEvent | PointerEvent | TouchEvent }
  | { reason: 'escape-key'; event: KeyboardEvent }
  | { reason: 'window-resize'; event: UIEvent }
  | { reason: 'item-press'; event: MouseEvent | PointerEvent | KeyboardEvent }
  | { reason: 'focus-out'; event: KeyboardEvent | FocusEvent }
  | { reason: 'list-navigation'; event: KeyboardEvent }
  | { reason: 'cancel-open'; event: MouseEvent }
  | { reason: 'none'; event: Event }
) & {
  /** Cancels Base UI from handling the event. */
  cancel: () => void;
  /** Allows the event to propagate in cases where Base UI will stop the propagation. */
  allowPropagation: () => void;
  /** Indicates whether the event has been canceled. */
  isCanceled: boolean;
  /** Indicates whether the event is allowed to propagate. */
  isPropagationAllowed: boolean;
  /** The element that triggered the event, if applicable. */
  trigger: Element | undefined;
};

Trigger

A button that opens the select popup. Renders a <button> element.

Trigger Props:

Trigger Data Attributes:

Trigger.Props

Re-export of Trigger props.

Trigger.State

type SelectTriggerState = {
  /** Whether the select popup is currently open. */
  open: boolean;
  /** Whether the select popup is readonly. */
  readOnly: boolean;
  /** Indicates which side the corresponding popup is positioned relative to its anchor. */
  popupSide: Side | null;
  /** The value of the currently selected item. */
  value: any;
  /** Whether the select doesn't have a value. */
  placeholder: boolean;
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

Value

A text label of the currently selected item. Renders a <span> element.

Value Props:

children Prop Example:

<Select.Value>{(value: string | null) => (value ? labels[value] : 'No value')}</Select.Value>

Value Data Attributes:

Value.Props

Re-export of Value props.

Value.State

type SelectValueState = {
  /** The value of the currently selected item. */
  value: any;
  /** Whether the placeholder is being displayed. */
  placeholder: boolean;
};

Icon

An icon that indicates that the trigger button opens a select popup. Renders a <span> element.

Icon Props:

Icon Data Attributes:

Icon.Props

Re-export of Icon props.

Icon.State

type SelectIconState = {
  /** Whether the select popup is currently open. */
  open: boolean;
};

List

A container for the select items. Renders a <div> element.

List Props:

List.Props

Re-export of List props.

List.State

type SelectListState = {};

Portal

A portal element that moves the popup to a different part of the DOM. By default, the portal element is appended to <body>. Renders a <div> element.

Portal Props:

Portal.Props

Re-export of Portal props.

Portal.State

type SelectPortalState = {};

Backdrop

An overlay displayed beneath the select popup. Renders a <div> element.

Backdrop Props:

Backdrop Data Attributes:

Backdrop.Props

Re-export of Backdrop props.

Backdrop.State

type SelectBackdropState = {
  /** Whether the component is open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

Positioner

Positions the select popup. Renders a <div> element.

Positioner Props:

alignOffset Prop Example:

<Positioner
  alignOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.width : anchor.height;
  }}
/>

sideOffset Prop Example:

<Positioner
  sideOffset={({ side, align, anchor, positioner }) => {
    return side === 'top' || side === 'bottom' ? anchor.height : anchor.width;
  }}
/>

collisionAvoidance Prop Example:

<Positioner
  collisionAvoidance={{
    side: 'shift',
    align: 'shift',
    fallbackAxisSide: 'none',
  }}
/>

Positioner Data Attributes:

Positioner CSS Variables:

Positioner.Props

Re-export of Positioner props.

Positioner.State

type SelectPositionerState = {
  /** Whether the component is open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side | 'none';
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the anchor element is hidden. */
  anchorHidden: boolean;
};

Popup

A container for the select list. Renders a <div> element.

Popup Props:

Popup Data Attributes:

Popup.Props

Re-export of Popup props.

Popup.State

type SelectPopupState = {
  /** The side of the anchor the component is placed on. */
  side: Side | 'none';
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the component is open. */
  open: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

Arrow

Displays an element positioned against the select popup anchor. Renders a <div> element.

Arrow Props:

Arrow Data Attributes:

Arrow.Props

Re-export of Arrow props.

Arrow.State

type SelectArrowState = {
  /** Whether the select popup is currently open. */
  open: boolean;
  /** The side of the anchor the component is placed on. */
  side: Side | 'none';
  /** The alignment of the component relative to the anchor. */
  align: Align;
  /** Whether the arrow cannot be centered on the anchor. */
  uncentered: boolean;
};

Item

An individual option in the select popup. Renders a <div> element.

Item Props:

Item Data Attributes:

Item.Props

Re-export of Item props.

Item.State

type SelectItemState = {
  /** Whether the item should ignore user interaction. */
  disabled: boolean;
  /** Whether the item is selected. */
  selected: boolean;
  /** Whether the item is highlighted. */
  highlighted: boolean;
};

Group

Groups related select items with the corresponding label. Renders a <div> element.

Group Props:

Group.Props

Re-export of Group props.

Group.State

type SelectGroupState = {};

GroupLabel

An accessible label that is automatically associated with its parent group. Renders a <div> element.

GroupLabel Props:

GroupLabel.Props

Re-export of GroupLabel props.

GroupLabel.State

type SelectGroupLabelState = {};

Separator

A visual separator between items or groups. Renders a <div> element.

Separator Props:

Separator.Props

Re-export of Separator props.

Separator.State

type SelectSeparatorState = {
  /** The orientation of the separator. */
  orientation: Orientation;
};

Label

An accessible label that is automatically associated with the select trigger. Renders a <div> element.

Label Props:

Label.Props

Re-export of Label props.

Label.State

type SelectLabelState = {
  /** Whether the component should ignore user interaction. */
  disabled: boolean;
  /** Whether the field has been touched. */
  touched: boolean;
  /** Whether the field value has changed from its initial value. */
  dirty: boolean;
  /** Whether the field is valid. */
  valid: boolean | null;
  /** Whether the field has a value. */
  filled: boolean;
  /** Whether the field is focused. */
  focused: boolean;
};

ItemText

A text label of the select item. Renders a <div> element.

ItemText Props:

ItemText.Props

Re-export of ItemText props.

ItemText.State

type SelectItemTextState = {};

ItemIndicator

Indicates whether the select item is selected. Renders a <span> element.

ItemIndicator Props:

ItemIndicator Data Attributes:

ItemIndicator.Props

Re-export of ItemIndicator props.

ItemIndicator.State

type SelectItemIndicatorState = {
  /** Whether the item is selected. */
  selected: boolean;
  /** The transition status of the component. */
  transitionStatus: TransitionStatus;
};

ScrollUpArrow

An element that scrolls the select popup up when hovered. Does not render when using touch input. Renders a <div> element.

ScrollUpArrow Props:

ScrollUpArrow Data Attributes:

ScrollUpArrow.Props

Re-export of ScrollUpArrow props.

ScrollUpArrow.State

type SelectScrollUpArrowState = {};

ScrollDownArrow

An element that scrolls the select popup down when hovered. Does not render when using touch input. Renders a <div> element.

ScrollDownArrow Props:

ScrollDownArrow Data Attributes:

ScrollDownArrow.Props

Re-export of ScrollDownArrow props.

ScrollDownArrow.State

type SelectScrollDownArrowState = {};

External Types

Side

type Side = 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';

Align

type Align = 'start' | 'center' | 'end';

OffsetFunction

type OffsetFunction = (data: {
  side: 'top' | 'bottom' | 'left' | 'right' | 'inline-end' | 'inline-start';
  align: 'start' | 'center' | 'end';
  anchor: { width: number; height: number };
  positioner: { width: number; height: number };
}) => number;

InteractionType

type InteractionType = 'mouse' | 'touch' | 'pen' | 'keyboard' | '';

Orientation

type Orientation = 'horizontal' | 'vertical';

Export Groups

• Select.Root: Select.Root, Select.Root.Props, Select.Root.State, Select.Root.Actions, Select.Root.ChangeEventReason, Select.Root.ChangeEventDetails
• Select.Label: Select.Label, Select.Label.State, Select.Label.Props
• Select.Trigger: Select.Trigger, Select.Trigger.State, Select.Trigger.Props
• Select.Value: Select.Value, Select.Value.State, Select.Value.Props
• Select.Icon: Select.Icon, Select.Icon.State, Select.Icon.Props
• Select.Portal: Select.Portal, Select.Portal.State, Select.Portal.Props
• Select.Backdrop: Select.Backdrop, Select.Backdrop.State, Select.Backdrop.Props
• Select.Positioner: Select.Positioner, Select.Positioner.State, Select.Positioner.Props
• Select.Popup: Select.Popup, Select.Popup.Props, Select.Popup.State
• Select.List: Select.List, Select.List.Props, Select.List.State
• Select.Item: Select.Item, Select.Item.State, Select.Item.Props
• Select.ItemIndicator: Select.ItemIndicator, Select.ItemIndicator.State, Select.ItemIndicator.Props
• Select.ItemText: Select.ItemText, Select.ItemText.State, Select.ItemText.Props
• Select.Arrow: Select.Arrow, Select.Arrow.State, Select.Arrow.Props
• Select.ScrollDownArrow: Select.ScrollDownArrow, Select.ScrollDownArrow.State, Select.ScrollDownArrow.Props
• Select.ScrollUpArrow: Select.ScrollUpArrow, Select.ScrollUpArrow.State, Select.ScrollUpArrow.Props
• Select.Group: Select.Group, Select.Group.State, Select.Group.Props
• Select.GroupLabel: Select.GroupLabel, Select.GroupLabel.State, Select.GroupLabel.Props
• Select.Separator: Select.Separator, Select.Separator.Props, Select.Separator.State
• Default: SelectRootProps, SelectRootState, SelectRootActions, SelectRootChangeEventReason, SelectRootChangeEventDetails, SelectLabelState, SelectLabelProps, SelectTriggerState, SelectTriggerProps, SelectValueState, SelectValueProps, SelectIconState, SelectIconProps, SelectPortalState, SelectPortalProps, SelectBackdropState, SelectBackdropProps, SelectPositionerState, SelectPositionerProps, SelectPopupProps, SelectPopupState, SelectListProps, SelectListState, SelectItemState, SelectItemProps, SelectItemIndicatorState, SelectItemIndicatorProps, SelectItemTextState, SelectItemTextProps, SelectArrowState, SelectArrowProps, SelectScrollDownArrowState, SelectScrollDownArrowProps, SelectScrollUpArrowState, SelectScrollUpArrowProps, SelectGroupState, SelectGroupProps, SelectGroupLabelState, SelectGroupLabelProps, SelectSeparatorProps, SelectSeparatorState

Canonical Types

Maps Canonical: Alias — Use Canonical when its namespace is already imported; otherwise use Alias.

• Select.Root.Props: SelectRootProps
• Select.Root.State: SelectRootState
• Select.Root.Actions: SelectRootActions
• Select.Root.ChangeEventReason: SelectRootChangeEventReason
• Select.Root.ChangeEventDetails: SelectRootChangeEventDetails
• Select.Label.State: SelectLabelState
• Select.Label.Props: SelectLabelProps
• Select.Trigger.State: SelectTriggerState
• Select.Trigger.Props: SelectTriggerProps
• Select.Value.State: SelectValueState
• Select.Value.Props: SelectValueProps
• Select.Icon.State: SelectIconState
• Select.Icon.Props: SelectIconProps
• Select.Portal.State: SelectPortalState
• Select.Portal.Props: SelectPortalProps
• Select.Backdrop.State: SelectBackdropState
• Select.Backdrop.Props: SelectBackdropProps
• Select.Positioner.State: SelectPositionerState
• Select.Positioner.Props: SelectPositionerProps
• Select.Popup.Props: SelectPopupProps
• Select.Popup.State: SelectPopupState
• Select.List.Props: SelectListProps
• Select.List.State: SelectListState
• Select.Item.State: SelectItemState
• Select.Item.Props: SelectItemProps
• Select.ItemIndicator.State: SelectItemIndicatorState
• Select.ItemIndicator.Props: SelectItemIndicatorProps
• Select.ItemText.State: SelectItemTextState
• Select.ItemText.Props: SelectItemTextProps
• Select.Arrow.State: SelectArrowState
• Select.Arrow.Props: SelectArrowProps
• Select.ScrollDownArrow.State: SelectScrollDownArrowState
• Select.ScrollDownArrow.Props: SelectScrollDownArrowProps
• Select.ScrollUpArrow.State: SelectScrollUpArrowState
• Select.ScrollUpArrow.Props: SelectScrollUpArrowProps
• Select.Group.State: SelectGroupState
• Select.Group.Props: SelectGroupProps
• Select.GroupLabel.State: SelectGroupLabelState
• Select.GroupLabel.Props: SelectGroupLabelProps
• Select.Separator.Props: SelectSeparatorProps
• Select.Separator.State: SelectSeparatorState