Select

Persistent single string-value selection with anchored option surface and listbox semantics on Web.

Distribution status

BeeUI 0.86.2-rc.3 is public on npm under the opt-in next dist-tag (observed 2026-09-25T06:25:18.371Z). latest currently resolves to 0.86.2-rc.3 and lags next until the owner moves it for all four packages. See Start for the full install commands. The import shape below works against the published package; the repository-local Registry command remains available as a no-registry-required alternative from a BeeUI checkout. Pin @0.86.2-rc.3 instead of @next for an immutable version in CI.

Identity

• Category: Forms & selection
• Status: stable public Registry/export-map component family
• Targets: iOS · Android · Web, subject to the compatibility contract
• Prerequisites: @beemvp/beeui-ui installed (or this component’s source copied via the Registry CLI below) and, on Web, the BeeUI Tailwind/Uniwind theme CSS loaded — see Start for full platform setup.
• Source: packages/ui/src/components/select.tsx

Import

import { Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue } from '@beemvp/beeui-ui';

There is no documented deep/private source import. For source ownership from a BeeUI checkout:

pnpm beeui add select

Registry (used throughout this page) is BeeUI’s source-ownership manifest — registry/registry.json — that the pnpm beeui/@beemvp/beeui-cli CLI reads to copy a component’s real source into your app and rewrite its internal imports; it is not an npm package index. This component’s own Registry entry: registry/registry.json.

Composition and public API

• Family exports: Select SelectContent SelectGroup SelectItem SelectLabel SelectTrigger SelectValue
  • Also routed here, outside the Registry family:
    • select
  • Package export subpath: @beemvp/beeui-ui/select

Exported types: SelectAlign, SelectCollisionPadding, SelectContentProps, SelectDirection, SelectGroupProps, SelectItemProps, SelectLabelProps, SelectOptionValue, SelectPlacement, SelectProps, SelectTriggerProps, SelectValueProps

The generated API inventory is mechanically joined to packages/ui/src/index.ts, Registry metadata, and the component reference contract. Each type’s field table below is parsed directly from that source, not a second hand-maintained copy; for the fuller behavior narrative see the canonical component behavior catalog.

State and behavior contract

Controlled (value/onValueChange) or uncontrolled (defaultValue) persistent single-value selection, independent of the anchored open/onOpenChange/defaultOpen presentation state; a duplicate SelectItem value disables every item sharing it and warns in development, and removing the selected option does not synthesize a value change — SelectValue falls back to its placeholder until a matching item returns.

Props

SelectContentProps

Prop	Type	Default	Description
align	SelectAlign	'start'	Where the overlay sits along the anchor’s cross axis — 'start', 'center' or 'end'. The anchored-overlay kernel may flip it when the preferred placement would collide with the viewport.
alignOffset	number	0	Pixels to shift the overlay along the alignment axis, after align is resolved.
avoidKeyboard	boolean	true	Whether the overlay repositions to stay clear of the on-screen keyboard.
avoidSafeArea	boolean	true	Whether the overlay keeps clear of the platform safe-area insets — notches, home indicators and status bars.
closeOnOutsidePress	boolean	true	Whether a press outside the overlay dismisses it.
collisionPadding	SelectCollisionPadding	8	Minimum distance to keep from the viewport edges when the kernel repositions or flips the overlay. A number applies to every edge; an object sets edges individually.
direction	SelectDirection	—	Logical direction used to resolve align/placement for RTL layouts. Defaults to the app’s resolved layout direction.
flip	boolean	true	Flips placement to the opposite side of the trigger when there is not enough room. Defaults to true.
listProps	Omit<ViewProps, 'children'>	—	Forwarded to the internal View that wraps the options on Web — a plain overflow View there, not a ScrollView (see #612 and scrollViewProps below), so this is typed to what a View actually honours. Excludes children, which this component owns. No effect on native — see scrollViewProps for that host.
maxHeight	number	—	Caps the listbox’s height; clamped to at least 96 and to the available viewport space. Defaults to 320.
outsidePressProps	Omit<PressableProps, 'children' | 'onPress' | 'style'>	—	Forwarded to the outside-press dismiss layer, excluding children/onPress/style, which this component owns.
outsidePressTestID	string	—	testID applied to the outside-press dismiss layer, for targeting it in tests.
placement	SelectPlacement	'bottom'	Which side of the trigger the listbox opens on. Defaults to 'bottom'.
scrollViewProps	Omit<ScrollViewProps, 'children'>	—	Forwarded to the internal ScrollView that wraps the options on native, excluding children, which this component owns. On Web the host is a plain overflow View (#612); for migration compatibility View-compatible fields are still forwarded there, with listProps winning conflicts. A dev warning asks Web consumers to migrate; ScrollView-only fields have no Web meaning.
shift	boolean	true	Shifts the listbox along the trigger’s edge to stay within the viewport instead of overflowing. Defaults to true.
sideOffset	number	6	Pixels of gap between the anchor and the overlay, along the placement side.

Also carries every prop of Omit<ViewProps, 'nativeID' | 'role'> — that upstream contract is not reproduced here.

SelectGroupProps

This type adds no fields of its own. These are the props the implementation reads from the base type below; everything else is passed straight through.

Prop	Default
children	—

Also carries every prop of Omit<ViewProps, 'accessibilityRole' | 'role'> — that upstream contract is not reproduced here.

SelectItemProps

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
onPress	PressableProps['onPress']	—	Called on press, before this item’s own selection logic runs.
textClassName	string	—	Applied to string/number children, which are wrapped in a Text; ignored for custom element children.
textValue	string	—	The plain-text label used for the trigger’s selected-value display, this item’s accessible name, and keyboard typeahead. Defaults to the item’s children if they are a plain string/number; required (with a dev-mode warning) when children is a custom element.
value (required)	SelectOptionValue	—	Identifies this option; matched against the parent Select’s value/defaultValue. A value duplicated by another item in the same Select is disabled with a dev-mode warning.

Also carries every prop of Omit<PressableProps, 'accessibilityRole' | 'children' | 'onPress' | 'role'> — that upstream contract is not reproduced here.

SelectLabelProps

Prop	Type	Default	Description
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Also carries every prop of Omit<RNTextProps, 'nativeID' | 'role'> — that upstream contract is not reproduced here.

SelectProps

SelectProps is exactly SelectBaseProps.

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
defaultOpen	boolean	false	Initial open state for uncontrolled usage. Ignored once open is controlled. Defaults to false.
defaultValue	SelectOptionValue	—	Initial selected value for uncontrolled usage. Ignored once value is controlled.
disabled	boolean	false	Prevents the trigger from opening the listbox and disables the root. Defaults to false.
locale	string	—	Locale of the built-in copy (SelectValue’s default placeholder). Explicit-only (ADR-008) — no ambient device/browser locale auto-detection; an unknown locale falls back to English. Defaults to 'en-US'.
onOpenChange	(open: boolean) => void	—	Called whenever the open state changes (trigger press, item selection, outside press, Escape). Required alongside open to make it controlled; otherwise falls back to internal open state with a dev-mode warning.
onValueChange	(value: SelectOptionValue) => void	—	Called with the newly selected SelectItem’s value. Required for enabled controlled value usage (logs a dev warning otherwise).
open	boolean	—	Controls whether the listbox is open. Open state becomes controlled only when this is a defined boolean and onOpenChange is a function; passing open={undefined} leaves it uncontrolled. Unlike value, presence of the key alone is not enough.
value	SelectOptionValue	—	The selected SelectItem’s value. Passing this key (even undefined) switches selection to controlled, requiring onValueChange.

SelectTriggerProps

Prop	Type	Default	Description
children	React.ReactNode	—	Content rendered inside this element. The family’s composition section states which children it expects.
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
indicator	React.ReactNode	—	Replaces the default chevron (⌄/⌃ for closed/open) shown at the trigger’s end.
onKeyDown	(event: WebKeyboardEvent) => void	—	Web only: called on every keydown on the trigger, before this component’s own ArrowUp/ArrowDown-opens-the-listbox handling runs. No-op on native.

Also carries every prop of Omit<PressableProps, 'accessibilityRole' | 'children' | 'role'> — that upstream contract is not reproduced here.

SelectValueProps

Prop	Type	Default	Description
className	string	—	Extra utility classes, merged after the component’s own via cn(...), so they win on conflict. An escape hatch for source-owned and application work, not a cross-engine portability guarantee.
placeholder	React.ReactNode	—	Shown when no SelectItem is selected. Also used, when a plain string, as the trigger’s fallback accessible name if no accessibilityLabel is set and the Select is not inside a Field. Defaults to the Select root’s locale copy ('Select an option' for 'en-US').

Also carries every prop of Omit<RNTextProps, 'children' | 'role'> — that upstream contract is not reproduced here.

Related exported types:

• SelectAlign — alias of AnchoredOverlayAlign.
• SelectCollisionPadding — alias of AnchoredOverlayCollisionPadding.
• SelectDirection — alias of AnchoredOverlayDirection.
• SelectOptionValue — alias of string.
• SelectPlacement — alias of AnchoredOverlayPlacement.

The executable fixtures below are the source-grounded usage examples; consumers should not infer state ownership from DOM structure or another UI library.

Provider and dependencies

• BeeUIProvider is required above this family because it participates in shared overlay/toast runtime infrastructure.
• Peer/native dependencies visible to this Registry item: react, react-native
• Registry dependency closure: core-overlay, overlay-runtime, text, theme, use-direction
• Safe-area ownership remains explicit: shell surfaces touching system edges opt into SafeArea; components do not silently invent app-shell insets.
• Web consumers load the BeeUI semantic theme CSS as documented in Web onboarding.

Platform behavior

This family ships no platform-specific file, but its source branches on Platform, so some behavior differs by target.

The same public family is exposed across the supported target matrix; meaningful platform differences remain governed by the compatibility contract.

Evidence classes are not equal and this page does not blur them: Web behavior is exercised in a real browser, while iOS and Android carry package/export and native-compile evidence, which is not device-runtime proof. The compatibility contract records which class each claim rests on.

Accessibility

• Roles this family assigns: combobox, group (Web), listbox (Web), option — set in select.tsx by the components themselves, not by the caller.
• Accessibility states and properties it sets: accessibilityElementsHidden, accessibilityHint, accessibilityLabel, accessibilityLabelledBy, accessible, controls, describedby (Web), disabled, expanded, haspopup, hidden, invalid, labelledby (Web), required, selected, text — read from select.tsx.

Keyboard/focus behavior, announcements, Dynamic Type/Web zoom, RTL and reduced-motion expectations are not derived here — see Accessibility overview, Keyboard & focus, RTL/localization and Large text & zoom. BeeUI does not claim universal accessibility certification from automated tests.

Styling and theming

• Style axes: none of its own — its appearance comes from tokens and your own classes; it also carries Omit<PressableProps, 'accessibilityRole' | 'children' | 'onPress' | 'role'>, Omit<PressableProps, 'accessibilityRole' | 'children' | 'role'>, Omit<RNTextProps, 'children' | 'role'>, Omit<RNTextProps, 'nativeID' | 'role'>, Omit<ViewProps, 'accessibilityRole' | 'role'>, Omit<ViewProps, 'nativeID' | 'role'>.
• Class-name surfaces: className, textClassName.

Colors, spacing and typography come from semantic tokens rather than from values written here — see Theming and Density. A className is an escape hatch for source-owned and application work, not a cross-engine portability guarantee.

Executable examples

• Primary executable fixture: apps/showcase/__tests__/dynamic-type-contract.test.tsx
• Additional fixture: apps/showcase/__tests__/helpers/select-anchor-seam.tsx
• Additional fixture: apps/showcase/__tests__/issue-141-rtl-overlay-acceptance.test.tsx
• Additional fixture: apps/showcase/__tests__/perf-overlay-latency.test.tsx

Addressable examples

Each link below opens the Showcase at that exact example, not at the top of the gallery:

• basic — smallest meaningful complete usage
• states — the states example
• uncontrolled — the uncontrolled example
• composition — the composition example

The Showcase links demonstrate Web behavior; use the native-preview guide for real simulator/emulator/device paths.

Live Web preview

This frame loads the real BeeUI Web Showcase on demand; it is not a second docs-only implementation. It proves browser behavior only. Use native preview for iOS/Android simulator, emulator or device paths.

Composition anatomy

• Family root / primary export: Select
  • Public composition parts / helpers:
    • SelectContent
    • SelectGroup
    • SelectItem
    • SelectLabel
    • SelectTrigger
    • SelectValue
  • Exported type surface:
    • SelectAlign
    • SelectCollisionPadding
    • SelectContentProps
    • SelectDirection
    • SelectGroupProps
    • SelectItemProps
    • SelectLabelProps
    • SelectOptionValue
    • SelectPlacement
    • SelectProps
    • SelectTriggerProps
    • SelectValueProps

The tree above is ordinary document structure so it remains readable with keyboard and assistive technology; it is derived from the real public export family rather than a canvas-only diagram.

Verified example source

These are the parts of the typechecked runtime Showcase fixture behind this live preview — apps/showcase/component-gallery/select-showcase.tsx, 311 lines — where Select is actually used: 64 lines in 6 places, of 10 in total — open the fixture for the remaining 4. Each block is copied verbatim from the line range named above it, so it is the same executable source, not a retelling of it. Other uses of this family, and the parts of the file exercising other families, are not reproduced here.

Imports the examples below need (a filtered subset of the fixture’s own top-level imports):

import { Dialog, Select, SelectContent, SelectGroup, SelectItem, SelectLabel, SelectTrigger, SelectValue, Text } from '@beemvp/beeui-ui';
import * as React from 'react';

Fixture state this block reads (same file, line 41):

  const [rootSelectOpen, setRootSelectOpen] = React.useState(false);

lines 57–64:

      <Select onOpenChange={setRootSelectOpen} open={rootSelectOpen}>
        <SelectTrigger testID="select-showcase-scope-root-trigger">
          <SelectValue placeholder="Root Select" />
        </SelectTrigger>
        <SelectContent testID="select-showcase-scope-root-content">
          <SelectItem value="root">Root option</SelectItem>
        </SelectContent>
      </Select>

Fixture state this block reads (same file, line 40):

  const [dialogSelectOpen, setDialogSelectOpen] = React.useState(false);

lines 73–80:

          <Select onOpenChange={setDialogSelectOpen} open={dialogSelectOpen}>
            <SelectTrigger testID="select-showcase-scope-child-trigger">
              <SelectValue placeholder="Dialog Select" />
            </SelectTrigger>
            <SelectContent testID="select-showcase-scope-child-content">
              <SelectItem value="child">Dialog option</SelectItem>
            </SelectContent>
          </Select>

lines 163–170:

                  <Select disabled defaultValue="locked">
                    <SelectTrigger testID="select-showcase-disabled-trigger">
                      <SelectValue />
                    </SelectTrigger>
                    <SelectContent>
                      <SelectItem value="locked">Managed by organization</SelectItem>
                    </SelectContent>
                  </Select>

lines 178–195:

                <Select defaultValue="tokyo">
                  <SelectTrigger accessibilityLabel="Office" testID="select-showcase-group-trigger">
                    <SelectValue />
                  </SelectTrigger>
                  <SelectContent>
                    <SelectGroup>
                      <SelectLabel>Asia Pacific</SelectLabel>
                      <SelectItem value="tokyo">Tokyo</SelectItem>
                      <SelectItem value="singapore">Singapore</SelectItem>
                      <SelectItem value="sydney">Sydney</SelectItem>
                    </SelectGroup>
                    <SelectGroup>
                      <SelectLabel>Europe</SelectLabel>
                      <SelectItem value="paris">Paris</SelectItem>
                      <SelectItem value="london">London</SelectItem>
                    </SelectGroup>
                  </SelectContent>
                </Select>

Fixture state this block reads (same file, lines 27, 29-31):

const SelectConsumerContext = React.createContext('select-context-default');
function SelectContextProbe({ testID }: { testID: string }) {
  return <Text testID={testID}>{`context: ${React.useContext(SelectConsumerContext)}`}</Text>;
}

lines 202–212:

                <Select defaultValue="context">
                  <SelectTrigger testID="select-showcase-context-trigger">
                    <SelectValue testID="select-showcase-context-value" />
                  </SelectTrigger>
                  <SelectContent testID="select-showcase-context-content">
                    <SelectItem textValue="Context-aware option" value="context">
                      <SelectContextProbe testID="select-showcase-context-probe" />
                    </SelectItem>
                    <SelectItem value="plain">Plain option</SelectItem>
                  </SelectContent>
                </Select>

lines 255–265:

                <Select defaultValue="very-long-option">
                  <SelectTrigger accessibilityLabel="Narrow Select" testID="select-showcase-narrow-trigger">
                    <SelectValue />
                  </SelectTrigger>
                  <SelectContent testID="select-showcase-narrow-content">
                    <SelectItem value="short">Short option</SelectItem>
                    <SelectItem value="very-long-option">
                      A long option label that must truncate safely in a narrow layout
                    </SelectItem>
                  </SelectContent>
                </Select>

Open the fixture itself for the full surrounding component. For a smaller app-specific example, start from the imports and fixture-state blocks above and keep only the state your screen owns.

Limitations

• Passing open without onOpenChange leaves the value read-only: the component renders what you passed and can never change it. It warns in development builds rather than failing silently in production.

Implementation note: Rendering a Select inside a Popover is supported: the two share the same anchored-overlay runtime and dismiss/collision handling, so the listbox opens above the popover rather than being clipped or hidden behind it.

Related

• All components
• Production patterns
• Showcase
• CLI & source ownership
• Source