feat(headless): add Select primitive

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -21,6 +21,10 @@
  "import": "./dist/primitives/popover/index.js",
  "types": "./dist/primitives/popover/index.d.ts"
  },
+ "./select": {
+ "import": "./dist/primitives/select/index.js",
+ "types": "./dist/primitives/select/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/select/README.md

@@ -0,0 +1,163 @@
+# Select
+
+A dropdown select component with keyboard navigation, typeahead, and optional item-to-trigger alignment. Replaces native `<select>` with a fully styled, accessible alternative.
+
+## When to Use
+
+- Picking a single value from a predefined list of options.
+- When you need typeahead, keyboard navigation, and full styling control.
+- Prefer Select over Autocomplete when the user should choose from a fixed list without typing to filter.
+
+## Usage
+
+```tsx
+import { Select } from '@/primitives/select';
+
+<Select.Root>
+ <Select.Trigger>
+ <Select.Value placeholder='Choose a fruit...' />
+ </Select.Trigger>
+ <Select.Positioner>
+ <Select.Popup>
+ <Select.Option
+ value='apple'
+ label='Apple'
+ />
+ <Select.Option
+ value='banana'
+ label='Banana'
+ />
+ <Select.Option
+ value='cherry'
+ label='Cherry'
+ />
+ </Select.Popup>
+ </Select.Positioner>
+</Select.Root>;
+```
+
+### Controlled
+
+```tsx
+const [value, setValue] = useState('apple');
+
+<Select.Root
+ value={value}
+ onValueChange={setValue}
+>
+ {/* ... */}
+</Select.Root>;
+```
+
+### With `items` for SSR label resolution
+
+The `items` prop allows label resolution before options mount (useful for server rendering or deferred lists):
+
+```tsx
+const items = [
+ { value: 'apple', label: 'Apple' },
+ { value: 'banana', label: 'Banana' },
+];
+
+<Select.Root
+ items={items}
+ defaultValue='apple'
+>
+ {/* Select.Value will display "Apple" even before Options mount */}
+</Select.Root>;
+```
+
+### Disable item-to-trigger alignment
+
+By default, the selected option visually aligns with the trigger. Disable this for standard dropdown positioning:
+
+```tsx
+<Select.Root alignItemWithTrigger={false}>{/* Uses standard Floating UI positioning */}</Select.Root>
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ------------------- | --------------- | ------------------------------------------ |
+| `Select.Root` | — | Root context provider |
+| `Select.Trigger` | `<button>` | Toggles the dropdown on click |
+| `Select.Value` | `<span>` | Displays the selected label or placeholder |
+| `Select.Portal` | — | Portals children (accepts `root` prop) |
+| `Select.Positioner` | `<div>` | Floating positioned container |
+| `Select.Popup` | `<div>` | Visual wrapper for the option list |
+| `Select.Option` | `<button>` | A selectable option |
+| `Select.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Select.Root`
+
+| Prop | Type | Default | Description |
+| ---------------------- | ------------------------- | ---------------- | ------------------------------------------------------------------ |
+| `value` | `string` | — | Controlled selected value |
+| `defaultValue` | `string` | — | Initial selected value (uncontrolled) |
+| `onValueChange` | `(value: string) => void` | — | Called when selection changes |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `items` | `SelectItem[]` | — | `{ label, value }` pairs for label resolution before options mount |
+| `alignItemWithTrigger` | `boolean` | `true` | Visually align selected option over the trigger |
+| `placement` | `Placement` | `"bottom-start"` | Floating UI placement |
+| `sideOffset` | `number` | `4` | Gap between trigger and popup (px) |
+
+### `Select.Value`
+
+| Prop | Type | Default | Description |
+| ------------- | ----------- | ------- | ------------------------------- |
+| `placeholder` | `ReactNode` | — | Shown when no value is selected |
+
+### `Select.Option`
+
+| Prop | Type | Default | Description |
+| ---------- | --------- | --------------------- | -------------------------------------- |
+| `value` | `string` | **required** | The option's value |
+| `label` | `string` | falls back to `value` | Display label, also used for typeahead |
+| `disabled` | `boolean` | — | Prevents selection |
+
+### `Select.Trigger`, `Select.Positioner`, `Select.Popup`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Select.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | ------------------------------------- |
+| `ArrowDown` | Move to next option |
+| `ArrowUp` | Move to previous option |
+| `Enter` / `Space` | Select the active option, close popup |
+| `Escape` | Close the popup |
+| Type a character | Jump to matching option (typeahead) |
+
+Typeahead also works while the popup is closed — it changes the selected value directly.
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ---------- | ---------------------------------------- |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"select-option"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Popup open state |
+| `data-cl-selected` | Option | The currently selected option |
+| `data-cl-active` | Option | The keyboard-highlighted option |
+| `data-cl-disabled` | Option | Disabled option |
+| `data-cl-side` | Positioner | Resolved placement side |
+
+## Important Notes
+
+- **`label` on `Select.Option`** drives both display in `Select.Value` and typeahead matching. If omitted, `value` is used for both.
+- **`items` prop** is only for label resolution — it does not control which options render. You still render `Select.Option` children yourself.
+- **Disabled options** can still receive keyboard focus but cannot be selected.
+
+## ARIA
+
+- Popup: `role="listbox"`
+- Option: `role="option"`, `aria-selected`, `aria-disabled`
+- Trigger: `aria-expanded`, `aria-haspopup="listbox"`, `aria-controls`

packages/headless/src/primitives/select/index.ts

@@ -0,0 +1,13 @@
+export * as Select from './parts';
+
+export type {
+ SelectArrowProps,
+ SelectItem,
+ SelectOptionProps,
+ SelectPopupProps,
+ SelectPortalProps,
+ SelectPositionerProps,
+ SelectProps,
+ SelectTriggerProps,
+ SelectValueProps,
+} from './parts';

packages/headless/src/primitives/select/parts.ts

@@ -0,0 +1,8 @@
+export { type SelectItem, type SelectProps, SelectRoot as Root } from './select-root';
+export { type SelectTriggerProps, SelectTrigger as Trigger } from './select-trigger';
+export { type SelectValueProps, SelectValue as Value } from './select-value';
+export { type SelectPortalProps, SelectPortal as Portal } from './select-portal';
+export { type SelectPositionerProps, SelectPositioner as Positioner } from './select-positioner';
+export { type SelectPopupProps, SelectPopup as Popup } from './select-popup';
+export { type SelectOptionProps, SelectOption as Option } from './select-option';
+export { type SelectArrowProps, SelectArrow as Arrow } from './select-arrow';

packages/headless/src/primitives/select/select-arrow.tsx

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function SelectArrow(props: SelectArrowProps) {
+ const { floatingContext, arrowRef, placement } = useSelectContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='select-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/select/select-context.ts

@@ -0,0 +1,51 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, type RefObject, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface SelectItem {
+ label: string;
+ value: string;
+}
+
+export interface SelectContextValue {
+ open: boolean;
+ items: SelectItem[] | undefined;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ selectedIndex: number | null;
+ selectedValue: string | undefined;
+ selectedLabel: string | null;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ popupRef: RefObject<HTMLDivElement | null>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ valueToLabelRef: React.MutableRefObject<Map<string, string>>;
+ selectedItemRef: React.MutableRefObject<HTMLElement | null>;
+ alignItemWithTrigger: boolean;
+ handleSelect: (value: string, index: number) => void;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+}
+
+export const SelectContext = createContext<SelectContextValue | null>(null);
+
+export function useSelectContext() {
+ const ctx = useContext(SelectContext);
+ if (!ctx) {
+ throw new Error('Select compound components must be used within <Select.Root>');
+ }
+ return ctx;
+}

packages/headless/src/primitives/select/select-option.tsx

@@ -0,0 +1,65 @@
+'use client';
+
+import { useListItem, useMergeRefs } from '@floating-ui/react';
+import React, { useEffect } from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectOptionProps extends ComponentProps<'button'> {
+ value: string;
+ label?: string;
+ disabled?: boolean;
+}
+
+export function SelectOption(props: SelectOptionProps) {
+ const { render, value, label, disabled, ...otherProps } = props;
+ const { activeIndex, selectedValue, getItemProps, handleSelect, valueToLabelRef, selectedItemRef } =
+ useSelectContext();
+
+ const displayLabel = label ?? value;
+ const { ref: itemRef, index } = useListItem({ label: displayLabel });
+
+ const isSelected = selectedValue === value;
+ const isActive = activeIndex === index;
+
+ useEffect(() => {
+ valueToLabelRef.current.set(value, displayLabel);
+ return () => {
+ valueToLabelRef.current.delete(value);
+ };
+ }, [value, displayLabel, valueToLabelRef]);
+
+ const combinedRef = useMergeRefs([itemRef, isSelected ? selectedItemRef : null]);
+
+ const state = {
+ selected: isSelected,
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-option',
+ ref: combinedRef,
+ role: 'option' as const,
+ 'aria-selected': isSelected,
+ 'aria-disabled': disabled || undefined,
+ tabIndex: isActive ? 0 : -1,
+ ...(getItemProps({
+ onClick() {
+ if (!disabled) handleSelect(value, index);
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ selected: (v: boolean) => (v ? { 'data-cl-selected': '' } : null),
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-popup.tsx

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useSelectContext } from './select-context';
+
+export interface SelectPopupProps extends ComponentProps<'div'> {}
+
+export function SelectPopup(props: SelectPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useSelectContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'select-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

packages/headless/src/primitives/select/select-portal.tsx

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useSelectContext } from './select-context';
+
+export interface SelectPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function SelectPortal(props: SelectPortalProps) {
+ const { mounted } = useSelectContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}