Select

Import

import { Select } from "@hope-ui/components/select";

Select is a compound component — a namespace object whose parts you compose yourself. See the Anatomy below for every part and how they nest.

Usage

Select.Root takes the whole option set as items and owns the state (selection, open/close, keyboard, type-ahead, positioning, ARIA); it renders no element of its own. Select.Trigger is the control the reader sees and the widget’s focus owner, holding a Select.Value (the current choice) and a Select.Icon (the chevron). Everything from Select.Portal down is the popup, and Select.List takes a render callback invoked once per items entry.

For the simplest case — an array of strings — there is nothing to configure: the item is its value, its label, and its type-ahead text.

<Select.Root items={["Apple", "Banana", "Cherry"]}>
  <Select.Trigger aria-label="Choose a fruit">
    <Select.Value placeholder="Pick a fruit" />
    <Select.Icon />
  </Select.Trigger>
  <Select.Portal>
    <Select.Positioner>
      <Select.Content>
        <Select.List>
          {(entry) => (
            <Select.Item item={entry}>
              <Select.ItemText>{entry as string}</Select.ItemText>
              <Select.ItemIndicator />
            </Select.Item>
          )}
        </Select.List>
      </Select.Content>
    </Select.Positioner>
  </Select.Portal>
</Select.Root>

Anatomy

The nesting below the portal is fixed, and it is Popover’s spine: Portal lifts the layer out of the page’s stacking and overflow contexts, Positioner is the element the positioning engine measures and moves, and Content is the card. Splitting the last two is what keeps them from fighting: the card’s enter/exit translate would otherwise collide with the translate() the engine writes onto the positioner.

Content and List stay distinct for a different reason: a role="listbox" may only contain options and groups, so anything that is not an option belongs in the card beside the list, never inside it.

Controlled value

Left uncontrolled, a Select owns its selection; defaultValue gives it a starting one. Drive value and handle onChange to own it yourself.

The value is a scalar in single mode — a single Select hands back the item itself, never [item], and null is how “nothing selected” is spelled. Whether it is a scalar or an array is inferred from selectionMode, so nothing is cast at the call site.

const [fruit, setFruit] = createSignal<string | null>("Cherry");
 
<Select.Root items={FRUIT_NAMES} value={fruit()} onChange={setFruit}>
  {/* … */}
</Select.Root>;

The open state works the same way: defaultOpen for uncontrolled, or open + onOpenChange to own it. Every path in and out — the trigger, a keystroke, Escape, an outside press, picking an option — routes through onOpenChange first.

<Select.Root open={open()} onOpenChange={setOpen}>…</Select.Root>

Your own objects

Your items are your own objects and stay that way: every question the Select asks about one is an accessor function, never a required key name.

• itemToValue — the selection identity (compared for equality, and the string a form submits). Defaults to String.
• itemToLabel — the display and type-ahead text. Defaults to itemToValue.
• isItemDisabled — whether the row is dimmed and skipped. skipDisabled (default true) governs the skipping; disable the whole control with disabled on Select.Root.

All three are answered from the data, before a row has mounted — which is what lets a closed Select run type-ahead over the whole set, and what lets it skip a disabled option it has never rendered.

<Select.Root
  items={fruits}
  itemToValue={(fruit) => String(fruit.id)}
  itemToLabel={(fruit) => fruit.name}
  isItemDisabled={(fruit) => fruit.outOfSeason}
  defaultValue={fruits[2]}
>
  {/* … */}
  <Select.List>{(fruit: Fruit) => <FruitItem fruit={fruit} />}</Select.List>
</Select.Root>

Selection modes

selectionMode controls how many options can be chosen at once — the same vocabulary Listbox uses, never a multiple boolean:

• single (default): one option; choosing another replaces it, and the popup closes.
• multiple: a set; the popup stays open while you tick rows, because shouldCloseOnSelect defaults to selectionMode !== "multiple".
• none: nothing is ever selected; the arrows and type-ahead still move the highlight. A menu of commands rather than a field.

The mode also types the value: scalar (V | null) in single, an array (V[]) in multiple.

A comma-joined list of labels overflows a trigger fast, so Select.Value takes a callback and lets you summarize the selection instead. It receives the selected items — an array in both modes, because that is the shape the underlying list holds.

<Select.Root selectionMode="multiple" value={fruits()} onChange={setFruits}>
  <Select.Trigger aria-label="Choose fruits">
    <Select.Value placeholder="Any fruit">
      {(values: Fruit[]) =>
        values.length === 1
          ? (values[0] as Fruit).name
          : `${values.length} fruits selected`
      }
    </Select.Value>
    <Select.Icon />
  </Select.Trigger>
  {/* … */}
</Select.Root>

With no children, Select.Value joins the selected labels with ", " — which is exactly right for a single Select, and the reason the callback exists for the others.

Groups and separators

Set groupToItems and items becomes your group entries: it flattens them into navigation order, which is the only thing the Select needs from a group. Your callback then goes one level up — it is invoked per group, and you iterate that group’s own items with a plain <For>.

The group’s name never reaches the Select: you render it from your own key, which is why there is no groupToLabel and no { label, items } shape to conform to. Wrap each section in a Select.Group with a Select.GroupLabel, and divide them with a Select.Separator. Keyboard navigation flows across groups as one list — the arrows skip the labels and the hairline.

// Nested straight from your API — no remapping, no required key names.
// [{ kind: "Citrus", fruits: [{ id, name }, …] }, …]
 
<Select.Root
  items={baskets}
  groupToItems={(basket) => basket.fruits}
  itemToValue={itemToValue}
  itemToLabel={itemToLabel}
>
  {/* … */}
  <Select.List>
    {(basket: Basket, index) => (
      <>
        <Show when={index() > 0}>
          <Select.Separator />
        </Show>
        <Select.Group>
          <Select.GroupLabel>{basket.kind}</Select.GroupLabel>
          <For each={basket.fruits}>
            {(fruit) => <FruitItem fruit={fruit} />}
          </For>
        </Select.Group>
      </>
    )}
  </Select.List>
</Select.Root>

Sizes

The size prop scales density across sm, md (the default), and lg — and it scales the trigger and the popup together, because the two have to agree: a lg control opening an md list looks broken. There is no color axis; a Select is a neutral control over a neutral overlay, and its only accents are the transient highlight and the persistent selection.

<Select.Root size="sm">…</Select.Root>
<Select.Root size="md">…</Select.Root>
<Select.Root size="lg">…</Select.Root>

Long option lists

The popup caps its height at the space measured to the viewport edge (--available-height) and Select.List scrolls inside the card, so the rounded corners and the border stay still while the rows move. Arrowing past the fold scrolls the highlighted row into view — in this pattern nothing else would, since no option ever takes DOM focus.

Nothing renders until the popup opens, either. The options are data held on Select.Root, not mounted elements, so a form with ten Selects mounts zero option lists; the closed control still runs type-ahead over the full set, still knows whether the list would be empty, and still server-renders every native <option> for autofill.

The popup

side picks which side of the trigger the popup prefers (default "bottom") and align skids it along that side’s cross axis (default "center") — but both are a preference, not a promise: near a viewport edge the card flips to the opposite side and slides to stay in view, and what the parts report as data-side / data-align is where it actually landed. The component’s own defaults are a sideOffset of 4 (the small gap a picker keeps from its control) and a collisionPadding of 8 (the gutter kept off the viewport edge).

The width is not a decision you make: the popup always matches the trigger, via the --anchor-width the positioner publishes and the recipe spends. That is what a Select is. Override the positioner slot if you need something else.

<Select.Root side="top" sideOffset={8} collisionPadding={16} flip={false}>
  …
</Select.Root>

Select.Portal renders the layer at the end of <body>, so a Select inside a scroll container, a table cell, or a transformed ancestor is never clipped by it — while the position stays glued to the trigger as the container scrolls (autoUpdate, on by default). Pass mount to portal somewhere else, and trackAnchorMotion for a trigger that moves under a CSS transform.

An open Select is modal by default: the rest of the page is hidden from assistive technology and body scroll is locked. Note what that does not include — no focus trap and no backdrop, because focus never leaves the trigger in the first place. Pass modal={false} to keep the page scrollable behind the popup.

Finally, allowsEmptyCollection (default false) keeps the popup shut when there is nothing to choose from — a guard only a data-driven option set can offer, since a DOM-registered collection is always empty before it opens.

Dismissal

An open Select light-dismisses three ways, each independently switchable: Escape, a pointer-down outside the popup, and focus landing outside it. All three are on by default, and focus returns to the trigger — where, in this pattern, it never left.

<Select.Root closeOnEscape={false} closeOnInteractOutside={false}>
  …
</Select.Root>

A Select nested inside a Dialog or a Popover takes the first Escape on its own and leaves the layer below it standing; set bubbles if you want one keystroke to take the whole chain.

<Select.Root bubbles={{ escapeKey: true }}>…</Select.Root>

Native form submission

Set name and the Select renders a real, visually-clipped <select> beside the trigger — so a plain <form> submit carries the choice with no extra wiring. The submitted strings are the itemToValue values (here, the fruit ids), not the labels. Add form to associate the field with a form by id.

Because it is a real <select> holding one <option> per item — server-side too — three things come for free that a hidden input cannot give you: the browser can autofill it, required genuinely blocks submission (and moves focus to the trigger rather than to a control nobody can see), and the form’s reset button puts the selection back to where it started.

<form onSubmit={handleSubmit}>
  <Select.Root
    name="fruit"
    required
    items={fruits}
    itemToValue={(f) => String(f.id)}
  >
    {/* … */}
  </Select.Root>
  <Button type="submit">Submit</Button>
</form>

Keyboard interactions

Select implements the WAI-ARIA 1.2 combobox keyboard pattern. Every key is handled on the trigger, because there is nowhere else for it to live: no option is ever focused, so no option ever receives a keystroke.

Type-ahead reads itemToLabel (else itemToValue) from your data rather than the rendered text, which is what lets a closed Select match a row that has never mounted. It is collator-backed with sensitivity: "base", so typing cafe matches Café. The closed-selects-outright shortcut is single mode only: in multiple, a repeated letter would select and immediately deselect, so a closed match sets the highlight for the next open instead.

Polymorphism

Render a part as a different element or component with the render prop — a function that receives the part’s computed props and spreads them onto your element. Every part except Select.Root and Select.Portal accepts it. There is no as prop; render is the single polymorphism API.

<Select.Trigger
  aria-label="Choose a fruit"
  render={(props) => (
    <button {...props} class="rounded-full border border-strong px-4 py-1.5" />
  )}
>
  <Select.Value placeholder="Pick a fruit" />
  <Select.Icon />
</Select.Trigger>

Setting class after the spread is what replaces the recipe’s trigger chrome rather than merging into it. Everything else rides through the spread untouched — the role="combobox", the popup ARIA, and the whole keymap.

If the target is not a real <button>, pass nativeButton={false} on Select.Trigger alongside it, so the disabled behavior switches to tabIndex / aria-disabled and keyboard activation is synthesized.

Theming

Select’s look comes from the active preset’s recipe. It is two surfaces in one recipe — a form control and a floating card — with a single size axis and no color axis. Override styling at three levels, applied in order (later wins a Tailwind conflict): recipe base → preset slotClasses → instance slotClasses / part class.

Part slots

Every styled part carries a data-slot attribute you can target, and each is addressable by name through slotClasses. There is no root slot (Select.Root renders no element) and no portal slot, for the same reason.

The positioner and the content also report the resolved geometry as data-side / data-align, and their transition state as data-presence — which is how the preset animates the card in from the trigger’s direction. The highlight is data-active on a row, never a hover: state: the keyboard and the pointer share one active option, so a hover background would paint a second highlight the moment the cursor lagged a frame behind.

[data-slot="select-content"][data-side="top"] { /* … */ }

Overriding one Select

Set slotClasses on Select.Root to reach any slot from one place, or put class on an individual part. Use literal class strings so your Tailwind build can see them.

<Select.Root
  slotClasses={{ content: "shadow-2xl", item: "rounded-md font-mono" }}
>
  {/* … */}
</Select.Root>

<Select.Trigger class="font-mono">…</Select.Trigger>

The two glyphs are per-instance overridable as plain children — Select.Icon and Select.ItemIndicator each render the theme’s default only when given none.

<Select.Icon>
  <CaretIcon />
</Select.Icon>

App-wide defaults and overrides

Set the default size, both glyphs, and global part classes for every Select through the theme with definePreset, then pass the derived preset to ThemeProvider. defaultProps resolve at instance ?? preset ?? builtin precedence, so an explicit prop on a single Select always wins.

import { definePreset } from "@hope-ui/theming";
import { hope } from "@hope-ui/presets/hope";
 
export const myPreset = definePreset(hope, {
  components: {
    select: {
      defaultProps: {
        size: "sm",
        chevronIcon: () => <CaretIcon />,
        checkIcon: () => <TickIcon />,
      },
      slotClasses: { content: "rounded-none" },
    },
  },
});

Both glyphs are factories (() => JSX.Element), never a built element: a preset value is one object shared by every instance, and an already-built Solid node would move rather than be reused.

size is the recipe’s only variant, so it is the one styling prop defaultable app-wide. Positioning, selectionMode, modal and the dismissal props change behavior rather than looks and stay on the instance.

API

Select.Root

Select.Root<V, M> is generic in your item type V and its selection mode M. It renders no host element, so it takes no native attributes — only the props below.

Select.Trigger

Plus every native <button> attribute — aria-label or aria-labelledby among them, and one of the two is required.

Select.Value

Plus every native <span> attribute except children.

Select.List

Plus every native <div> attribute except children.

Select.Item

Plus every native <div> attribute — id is the exception: it is the aria-activedescendant target and is generated for you. Nothing else about the row is declared here; its label, disabled state and value all come from Select.Root’s accessors.

Select.Portal

Part props

Select.Icon, Select.Positioner, Select.Content, Select.Group, Select.GroupLabel, Select.Separator, Select.ItemText, and Select.ItemIndicator each accept their native element attributes plus a render prop and a class. Select.Icon and Select.ItemIndicator also take children — a custom glyph replacing the theme’s default for that one instance; aria-hidden is the one attribute neither forwards, since the trigger’s aria-expanded and the option’s aria-selected already convey what they show.

Accessibility

Select implements the WAI-ARIA combobox pattern (ARIA 1.2), with a role="listbox" popup.

• Give the trigger an accessible name. There is no Label part, so pass aria-label — or aria-labelledby pointing at your own <label> — on Select.Trigger. A nameless role="combobox" is an axe aria-input-field-name violation, and the popup inherits its name from the trigger, so one missing attribute leaves both unnamed.
• The value is announced before the label. Select.Value registers its id and it is prepended to the trigger’s aria-labelledby — content-based naming would read them the other way round, which is backwards for a field whose whole purpose is its value.
• Focus never leaves the trigger. No option ever takes DOM focus; the highlight is aria-activedescendant on the trigger plus data-active on the row, and that attribute is additionally gated on the widget actually holding focus, so the highlight never lingers after you tab away.
• No dangling IDREFs. aria-controls and aria-activedescendant are present only while the popup is open, so a page of closed Selects carries no attribute naming an element that isn’t in the DOM.
• Roles and state are wired for you. The trigger is role="combobox" with aria-haspopup and aria-expanded, the list role="listbox" (with aria-multiselectable in multiple mode), each option role="option" with aria-selected, groups role="group", and the separator role="presentation" — never role="separator", which is an invalid listbox child.
• One highlight, keyboard and pointer. The arrows and the cursor share a single active option, so the two can never paint two highlights; the selection check is separate from that transient highlight. Opening on Enter or Space lands on the selected option, and an offscreen highlight is scrolled into view.
• Disabled options stay discoverable. A disabled row keeps aria-disabled and, by default, is skipped by navigation; it can never be selected.
• A real form control underneath. With name, the clipped <select> is what browser autofill matches, what makes required genuinely block a submit (moving focus to the visible trigger), and what a native form reset restores.
• Motion is reduced-motion aware. The card’s fade-and-scale drops to an instant open/close when the user has prefers-reduced-motion enabled.