Skip to content
Porcelana

Select

Accessible dropdown select with grouped, disabled and checked items.

Example

Example.tsx
import { Field, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@porcelana/ui";

export default function Example() {
  return (
    <div style={{ maxWidth: 360 }}>
      <Field label="Sound">
        <Select defaultValue="chime">
          <SelectTrigger>
            <SelectValue placeholder="Choose a sound" />
          </SelectTrigger>
          <SelectContent>
            <SelectItem value="birds">Birdsong</SelectItem>
            <SelectItem value="chime">Morning chime</SelectItem>
            <SelectItem value="bells">Soft bells</SelectItem>
            <SelectItem value="radio" disabled>
              Radio (offline)
            </SelectItem>
          </SelectContent>
        </Select>
      </Field>
    </div>
  );
}

Import

Import
import { Select, SelectTrigger, SelectItem, SelectContent } from "@porcelana/ui";
import "@porcelana/ui/styles.css"; // once, at your app root

Props

Generated from the TypeScript types. Standard HTML attributes are passed through and not listed.

Select

PropTypeDefaultDescription
autoCompletestring–Browser autofill hint for the hidden native select.
defaultOpenboolean–Initial open state when uncontrolled.
defaultValuestring–Initial value when uncontrolled.
dirDirection–Reading direction for keyboard navigation ("ltr" or "rtl").
disabledboolean–Prevents interaction and dims the control.
formstring–Id of the form this control belongs to.
namestring–Field name submitted with a form.
onOpenChange((open: boolean) => void)–Called when the open state changes.
onValueChange((value: string) => void)–Called with the new value.
openboolean–Controlled open state. Use with onOpenChange.
requiredboolean–Marks the control as required in forms.
valuestring–Controlled value. Use with onValueChange.

SelectTrigger

PropTypeDefaultDescription
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
asChildboolean–Render the single child element instead, merging props and behaviour onto it.
disabledboolean–Prevents interaction and dims the control.
idstring–Element id. Generated automatically when omitted.
type"button" | "submit" | "reset"–Button type (defaults to "button").

SelectItem

PropTypeDefaultDescription
valuerequiredstring–Controlled value. Use with onValueChange.
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
asChildboolean–Render the single child element instead, merging props and behaviour onto it.
disabledboolean–Prevents interaction and dims the control.
idstring–Element id. Generated automatically when omitted.
textValuestring–Text used for typeahead when the item's content isn't plain text.

SelectContent

PropTypeDefaultDescription
align"center" | "start" | "end"–Alignment against the trigger.
alignOffsetnumber–Offset from the alignment edge in px.
aria-labelstring–Defines a string value that labels the current element. @see aria-labelledby.
arrowPaddingnumber–Padding between the arrow and the content edges in px.
asChildboolean–Render the single child element instead, merging props and behaviour onto it.
avoidCollisionsboolean–Flip or shift to stay on screen.
collisionBoundaryBoundary | Boundary[]–Element(s) used as the collision boundary instead of the viewport.
collisionPaddingnumber | Partial<Record<"top" | "right" | "bottom" | "left", number>>8Space to keep from the viewport edges in px.
forceMounttrue–Used to force mounting when more control is needed. Useful when controlling animation with React animation libraries.
hideWhenDetachedboolean–Hide when the trigger scrolls out of view.
idstring–Element id. Generated automatically when omitted.
onCloseAutoFocus((event: Event) => void)–Event handler called when auto-focusing on close. Can be prevented.
onEscapeKeyDown((event: KeyboardEvent) => void)–Event handler called when the escape key is down. Can be prevented.
onPointerDownOutside((event: PointerDownOutsideEvent) => void)–Event handler called when the a `pointerdown` event happens outside of the `DismissableLayer`. Can be prevented.
positionPositionpopper"popper" places the list next to the trigger; "item-aligned" overlays it like a native select.
side"top" | "right" | "bottom" | "left"–Preferred side of the trigger to render on.
sideOffsetnumber8Distance from the trigger in px.
stickySticky–Keep the content attached while scrolling.
updatePositionStrategyUpdatePositionStrategy–"optimized" or "always" recompute the position on every frame.

Accessibility

  • Follows the select-only combobox pattern: arrows move, typeahead jumps, Enter picks, Escape closes.
  • Wrap the trigger in Field to label it.

Mobile

  • 48px trigger and 44px options; the list stays within the screen with 8px of padding.