> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Select Component: Accessible Dropdown for React Apps

> The Clementine DS Select renders an accessible dropdown with searchable options, error states, and token-bound styling for all interaction states.

`Select` is Clementine DS's single-choice dropdown picker. It wraps Mantine's `Select` component — which is itself built on top of Mantine's `Combobox` primitive — and re-exports it with Clementine token bindings applied through `ClementineDSProvider`. Import from `@clementine-ds/ui`, not from `@mantine/core` directly.

> [!WARNING]
>
> **Draft** — `Select` is a Draft component. It renders correctly and all documented props are functional, but the ARIA pattern (combobox vs. listbox) has not been finalized. Token values are not yet validated against the rendered output.

Use `Select` when you have a short-to-medium closed list of known options and want users to pick exactly one. For open-ended type-ahead search, use a Combobox (not yet in this DS). For mutually exclusive selections with three or fewer options, consider `Radio` instead.

***

## When to use

* You have a predefined, closed list of options — a user cannot enter a value that isn't in the list.
* The list is short to medium in length (typically under \~50 items before UX degrades).
* You need optional type-ahead filtering so users can narrow the list by typing.
* You need a single selection — for multi-select, a different component is required (not yet in this DS).

## When not to use

* **Free-form text with suggestions** — use a Combobox or `Autocomplete` (not yet in this DS). `Select` does not allow custom values.
* **Two or three exclusive options** — a `Radio` group is more scannable and doesn't require opening a dropdown.
* **Boolean toggle** — use a `Checkbox` or `Switch`.
* **Multiple selections from a list** — use a MultiSelect (not yet in this DS).

***

## Usage

```tsx theme={null}
import { Select } from '@clementine-ds/ui';

// Basic usage
<Select
  label="Country"
  placeholder="Pick a country"
  data={['Australia', 'Canada', 'Germany', 'Japan', 'United States']}
/>

// With object data (value/label pairs)
<Select
  label="Status"
  placeholder="Select a status"
  data={[
    { value: 'active', label: 'Active' },
    { value: 'inactive', label: 'Inactive' },
    { value: 'pending', label: 'Pending review' },
  ]}
/>

// Required field with description
<Select
  label="Role"
  description="Users can have one role at a time."
  placeholder="Choose a role"
  data={['Admin', 'Editor', 'Viewer']}
  required
/>

// Error state
<Select
  label="Team"
  placeholder="Select a team"
  data={['Engineering', 'Design', 'Product']}
  error="You must select a team to continue."
/>

// Searchable — filters options as the user types
<Select
  label="Framework"
  placeholder="Search or pick…"
  data={['React', 'Angular', 'Vue', 'Svelte', 'SolidJS']}
  searchable
  nothingFoundMessage="No matching framework"
/>

// Clearable — shows a ✕ button when a value is selected
<Select
  label="Priority"
  placeholder="Pick a priority"
  data={['Low', 'Medium', 'High', 'Critical']}
  defaultValue="Medium"
  clearable
/>

// Disabled
<Select
  label="Region"
  placeholder="Not configurable"
  data={['US-East', 'US-West', 'EU-Central']}
  disabled
/>
```

### Controlled usage

```tsx theme={null}
import { useState } from 'react';
import { Select } from '@clementine-ds/ui';

function StatusPicker() {
  const [value, setValue] = useState<string | null>(null);

  return (
    <Select
      label="Status"
      placeholder="Pick a status"
      data={[
        { value: 'active', label: 'Active' },
        { value: 'inactive', label: 'Inactive' },
        { value: 'pending', label: 'Pending review' },
      ]}
      value={value}
      onChange={setValue}
    />
  );
}
```

### Grouped options

```tsx theme={null}
import { Select } from '@clementine-ds/ui';

<Select
  label="Tech stack"
  placeholder="Pick a technology"
  data={[
    { group: 'Frontend', items: ['React', 'Vue', 'Svelte'] },
    { group: 'Backend', items: ['Node.js', 'Django', 'Rails'] },
  ]}
/>
```

### Custom option rendering

```tsx theme={null}
import { Group, Select } from '@clementine-ds/ui';
import type { SelectProps } from '@clementine-ds/ui';

const renderOption: SelectProps['renderOption'] = ({ option, checked }) => (
  <Group gap="xs">
    <span>{option.label}</span>
    {checked && <span aria-hidden>✓</span>}
  </Group>
);

<Select
  label="Alignment"
  placeholder="Choose alignment"
  data={[
    { value: 'left', label: 'Left' },
    { value: 'center', label: 'Center' },
    { value: 'right', label: 'Right' },
  ]}
  renderOption={renderOption}
/>
```

***

## Props

`SelectProps` extends Mantine's `SelectProps` directly. The table below covers the props you'll use most often.

| Prop | Type | Default | Description |
| - | - | - | - |
| `data` | `ComboboxData` | — | The list of options. Accepts an array of strings, `{ value, label }` objects, or groups of either. Values must be unique. |
| `label` | `React.ReactNode` | — | Renders a `<label>` element tied to the input. Always provide a label unless you set `aria-label`. |
| `description` | `React.ReactNode` | — | Helper text displayed below the label. Not shown when omitted. |
| `placeholder` | `string` | — | Displayed when no value is selected. |
| `error` | `React.ReactNode` | — | Error message rendered below the input. Triggers error border and text color. Pass `true` for error styling without a message. |
| `required` | `boolean` | — | Adds the `required` attribute and appends a red asterisk to the label. |
| `withAsterisk` | `boolean` | — | Shows the required asterisk next to the label without setting `required` on the element. |
| `disabled` | `boolean` | — | Disables the input — no suggestions are shown and `onChange` is not called. |
| `value` | `string \| null` | — | Controlled selected value. |
| `defaultValue` | `string \| null` | — | Uncontrolled initial value. |
| `onChange` | `(value: string \| null, option: ComboboxItem) => void` | — | Called when the selected value changes. Receives the new value string and the full option object. |
| `searchable` | `boolean` | — | Allows the user to type to filter options. |
| `searchValue` | `string` | — | Controlled search input value. |
| `onSearchChange` | `(value: string) => void` | — | Called when the search input changes. Use with `searchValue` for controlled search. |
| `nothingFoundMessage` | `React.ReactNode` | — | Message shown when no options match the search query. If not set, the dropdown closes when empty. |
| `clearable` | `boolean` | — | Shows a clear button in the right section when a value is selected. |
| `clearButtonProps` | `InputClearButtonProps` | — | Props for the clear button — use to set `aria-label` on the clear button. |
| `allowDeselect` | `boolean` | `true` | Allows clicking the selected option to deselect it. |
| `autoSelectOnBlur` | `boolean` | — | Automatically selects the highlighted option when the input loses focus. Only works with `searchable`. |
| `openOnFocus` | `boolean` | — | Opens the dropdown when the input receives focus. Only works with `searchable`. |
| `dropdownOpened` | `boolean` | — | Controlled dropdown open state. |
| `defaultDropdownOpened` | `boolean` | — | Uncontrolled dropdown initial open state. |
| `onDropdownOpen` | `() => void` | — | Called when the dropdown opens. |
| `onDropdownClose` | `() => void` | — | Called when the dropdown closes. |
| `renderOption` | `(item: ComboboxLikeRenderOptionInput) => ReactNode` | — | Custom render function for each option row. |
| `filter` | `OptionsFilter` | — | Custom filter function. Receives `{ options, search, limit }`. |
| `limit` | `number` | `Infinity` | Maximum number of options to render at once. Use with large lists for performance. |
| `maxDropdownHeight` | `string \| number` | `250` | Max height of the dropdown scroll area. |
| `withScrollArea` | `boolean` | `true` | Wraps the options list in `ScrollArea.AutoSize`. Set to `false` to use native scroll. |
| `checkIconPosition` | `"left" \| "right"` | `"left"` | Position of the checkmark on the selected option. |
| `withCheckIcon` | `boolean` | `true` | Whether to show a checkmark on the selected option. |
| `comboboxProps` | `ComboboxProps` | — | Props passed to the underlying `Combobox` component — control `position`, `withinPortal`, `zIndex`, `transitionProps`, and more. |
| `leftSection` | `React.ReactNode` | — | Content rendered on the left side of the trigger input. |
| `rightSection` | `React.ReactNode` | — | Content rendered on the right side of the trigger input. |
| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl"` | `"sm"` | Controls input height, horizontal padding, and font size. |
| `radius` | `MantineRadius \| number` | — | Sets `border-radius`. Accepts theme radius keys or a raw CSS value. |
| `withErrorStyles` | `boolean` | — | Set to `false` to suppress error border/text color while still displaying the error message. |
| `readOnly` | `boolean` | — | Makes the input read-only — suggestions are not shown and `onChange` is not called. |
| `loading` | `boolean` | — | Displays a loading spinner inside the input. |

***

## Interaction states

| State | Trigger | Visual change |
| - | - | - |
| **Default** | Idle, no value | `select.bg.trigger` background, `select.border.default` border, placeholder in `select.fg.placeholder` |
| **Hover** | Mouse enters the trigger | `select.border.focus` border tint |
| **Focus** | Trigger receives keyboard or click focus | `select.border.focus` border + `select.ring` focus ring |
| **Open** | Dropdown is expanded | Popover renders with `select.bg.popover` background; caret rotates |
| **Disabled** | `disabled` prop is set | `select.bg.trigger-disabled` background, pointer events removed |
| **Error** | `error` prop is set | `select.border.error` border, error message in `feedback.error` color |

***

## Token contract

| Token | Semantic alias |
| - | - |
| `select.bg.trigger` | `surface.elevated` |
| `select.bg.trigger-disabled` | `surface.subtle` |
| `select.bg.popover` | `surface.overlay` |
| `select.option.bg-default` | `surface.elevated` |
| `select.option.bg-hover` | `surface.hover` |
| `select.option.bg-selected` | `surface.selected` |
| `select.option.fg-default` | `text.primary` |
| `select.option.fg-selected` | `text.accent` |
| `select.fg.value` | `text.primary` |
| `select.fg.placeholder` | `text.secondary` |
| `select.border.default` | `border.strong` |
| `select.border.focus` | `border.focus` |
| `select.border.error` | `feedback.error` |
| `select.ring` | `focus.ring` |
| `select.radius` | `radius.input` |

***

## Accessibility

* Always supply a visible `label` prop. Set `aria-label` only when no visible label is possible.
* When `clearable` is set, add an `aria-label` to the clear button via `clearButtonProps`: `clearButtonProps={{ 'aria-label': 'Clear selection' }}`. Without this, the clear button has no accessible name.
* Use `nothingFoundMessage` when `searchable` is enabled — a silent empty dropdown is confusing for screen-reader users.
* The underlying Mantine `Select` is built on the `Combobox` pattern. The exact ARIA roles (`combobox` + `listbox`) are provided by Mantine. **Note:** the Clementine DS spec has an open item to formally decide between the `combobox` and `listbox` ARIA patterns — see the draft status note below.
* Keyboard navigation: `Tab` / `Shift+Tab` to move in and out of the trigger, `Space` or `Enter` to open the dropdown, `↑` / `↓` to move between options, `Enter` to select, `Escape` to close.

***

## Draft status

`Select` carries a **Draft** status as of `clementine-ds@HEAD (2026-06-08)`. The following items are still open:

* **ARIA pattern decision** — the spec has not yet decided whether to use a `combobox` (text input + listbox) or `listbox` (button + listbox) ARIA pattern. Mantine defaults to `combobox`. This is under review.
* Storybook stories are missing for: empty state, long list (overflow), and error state.
* Token values (`select.border.focus` hover tint, `select.option.*`, `select.radius`) are defined in the spec but not yet validated against the rendered output.

Do not build production-critical token overrides against this component until these items are resolved.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.