Example
Example.tsximport { 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
Importimport { 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
| Prop | Type | Default | Description |
|---|
autoComplete | string | – | Browser autofill hint for the hidden native select. |
|---|
defaultOpen | boolean | – | Initial open state when uncontrolled. |
|---|
defaultValue | string | – | Initial value when uncontrolled. |
|---|
dir | Direction | – | Reading direction for keyboard navigation ("ltr" or "rtl"). |
|---|
disabled | boolean | – | Prevents interaction and dims the control. |
|---|
form | string | – | Id of the form this control belongs to. |
|---|
name | string | – | 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. |
|---|
open | boolean | – | Controlled open state. Use with onOpenChange. |
|---|
required | boolean | – | Marks the control as required in forms. |
|---|
value | string | – | Controlled value. Use with onValueChange. |
|---|
SelectTrigger
| Prop | Type | Default | Description |
|---|
aria-label | string | – | Defines a string value that labels the current element.
@see aria-labelledby. |
|---|
asChild | boolean | – | Render the single child element instead, merging props and behaviour onto it. |
|---|
disabled | boolean | – | Prevents interaction and dims the control. |
|---|
id | string | – | Element id. Generated automatically when omitted. |
|---|
type | "button" | "submit" | "reset" | – | Button type (defaults to "button"). |
|---|
SelectItem
| Prop | Type | Default | Description |
|---|
valuerequired | string | – | Controlled value. Use with onValueChange. |
|---|
aria-label | string | – | Defines a string value that labels the current element.
@see aria-labelledby. |
|---|
asChild | boolean | – | Render the single child element instead, merging props and behaviour onto it. |
|---|
disabled | boolean | – | Prevents interaction and dims the control. |
|---|
id | string | – | Element id. Generated automatically when omitted. |
|---|
textValue | string | – | Text used for typeahead when the item's content isn't plain text. |
|---|
SelectContent
| Prop | Type | Default | Description |
|---|
align | "center" | "start" | "end" | – | Alignment against the trigger. |
|---|
alignOffset | number | – | Offset from the alignment edge in px. |
|---|
aria-label | string | – | Defines a string value that labels the current element.
@see aria-labelledby. |
|---|
arrowPadding | number | – | Padding between the arrow and the content edges in px. |
|---|
asChild | boolean | – | Render the single child element instead, merging props and behaviour onto it. |
|---|
avoidCollisions | boolean | – | Flip or shift to stay on screen. |
|---|
collisionBoundary | Boundary | Boundary[] | – | Element(s) used as the collision boundary instead of the viewport. |
|---|
collisionPadding | number | Partial<Record<"top" | "right" | "bottom" | "left", number>> | 8 | Space to keep from the viewport edges in px. |
|---|
forceMount | true | – | Used to force mounting when more control is needed. Useful when
controlling animation with React animation libraries. |
|---|
hideWhenDetached | boolean | – | Hide when the trigger scrolls out of view. |
|---|
id | string | – | 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. |
|---|
position | Position | popper | "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. |
|---|
sideOffset | number | 8 | Distance from the trigger in px. |
|---|
sticky | Sticky | – | Keep the content attached while scrolling. |
|---|
updatePositionStrategy | UpdatePositionStrategy | – | "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.