Select

Select is the primitive for picking one value from a list: difficulty pickers, region menus, sort dropdowns, and any “choose one” control. It coordinates open state, the selected value, item registration, popper positioning, and outside-press dismissal so your component only has to render a trigger, a value label, and the items.

Reach for Select when a control needs to hold a single value, open an anchored popup over a trigger, and dismiss predictably on selection or an outside interaction.

Import

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

Anatomy

Root, Trigger, Portal, Content, and at least one Item form the minimum useful select. Value, Group, Label, and Separator are optional and help you structure the trigger label and the list.

<Select.Root>
  <Select.Trigger>
    <Select.Value />
  </Select.Trigger>
  <Select.Portal>
    <Select.Content>
      <Select.Group>
        <Select.Label />
        <Select.Item value="..." />
        <Select.Separator />
        <Select.Item value="..." />
      </Select.Group>
    </Select.Content>
  </Select.Portal>
</Select.Root>

Example

A controlled select for a match difficulty, with a placeholder, a labelled group, and a disabled option.

import { useState } from "@rbxts/react";
import { Select } from "@lattice-ui/select";

export function DifficultySelect() {
  const [value, setValue] = useState<string>();

  return (
    <Select.Root value={value} onValueChange={setValue}>
      <Select.Trigger>
        <Select.Value placeholder="Choose difficulty" />
      </Select.Trigger>

      <Select.Portal>
        <Select.Content placement="bottom" sideOffset={6}>
          <frame
            AutomaticSize={Enum.AutomaticSize.Y}
            BackgroundColor3={Color3.fromRGB(47, 53, 68)}
            BorderSizePixel={0}
            Size={UDim2.fromOffset(220, 0)}
          >
            <uilistlayout SortOrder={Enum.SortOrder.LayoutOrder} />

            <Select.Group>
              <Select.Label>
                <textlabel
                  BackgroundTransparency={1}
                  Size={UDim2.fromOffset(220, 20)}
                  Text="Standard"
                  TextColor3={Color3.fromRGB(168, 176, 191)}
                  TextSize={13}
                />
              </Select.Label>

              <Select.Item value="easy" textValue="Easy" />
              <Select.Item value="normal" textValue="Normal" />
              <Select.Separator />
              <Select.Item value="hard" textValue="Hard" />
              <Select.Item value="nightmare" textValue="Nightmare" disabled />
            </Select.Group>
          </frame>
        </Select.Content>
      </Select.Portal>
    </Select.Root>
  );
}

How it behaves

Open state

Select.Root is controllable. Pass open and onOpenChange to control it, or defaultOpen to run uncontrolled (defaults to false). Select.Trigger toggles open on activation and on Return/Space, and selecting an item closes it. When the root is disabled, the trigger cannot open the content.

Value and selection

The selected value is a single string. Select.Root is controllable via value/onValueChange, or uncontrolled via defaultValue. Each Select.Item registers itself with the root on mount — recording its value, textValue, disabled state, and document order — so the root always knows the full ordered set of options. Activating an item (click, Return, or Space) sets the value and closes the content. Selecting a disabled item is ignored, and if the current value ever points at a disabled or missing item, the root falls back to the first enabled item.

The value label

Select.Value reads the current value from context and renders the matching item’s textValue (falling back to the raw value, then to placeholder when nothing is selected). Because the label resolves through the item registry, it stays correct without you wiring text manually.

Positioning

Select.Content is positioned with popper, anchored to the trigger. Control the side with placement ("top" | "bottom" | "left" | "right", defaulting to "bottom"), nudge it with sideOffset and alignOffset, and keep it inside the viewport with collisionPadding. The content is measured and flipped automatically when it would collide with an edge.

Dismissal

Select.Content participates in dismissable-layer behavior in non-modal mode: interaction behind it is not blocked, but an outside press closes it. Use onPointerDownOutside and onInteractOutside to observe those interactions before the content dismisses.

Motion and presence

Select.Content runs a default popper entrance/exit recipe — a canvas-group reveal by default, or a transform-based reveal when asChild is set. Override it with transition, and pass forceMount to keep the content mounted through its exit animation.

API reference

Select.Root

Select.Trigger

Select.Value

Select.Portal

Select.Content

Select.Item

Select.Group

Select.Label

Select.Separator

Related

• Positioning with Popper
• Portals and layers
• Controlled state
• Presence and motion
• asChild composition