# Select

Page: /docs/components/select

{/* Figma: Meridian → Select (docs 34:106, component set 20:8926). Spec: docs/design-system/meridian/select.md */}

A field that opens a list of options. The same frame as Input, with label, description and error built in, 40 high with a 16 value and a 14 label. On HubSpot forms it asks for country, company size and how people heard about us. To pick several, use Multi-select.

```tsx
import { Select } from "@commenda/meridian/ui/select";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const SIZES = ["1 to 10", "11 to 50", "51 to 200", "201 to 1,000", "1,000+"].map((s) => ({
	value: s,
	label: `${s} employees`,
}));

export function SelectSingle() {
	return (
		<Fields>
			<Select label="Company size" options={SIZES} placeholder="Select a company size" />
			<Select label="Company size" options={SIZES} defaultValue="51 to 200" />
		</Fields>
	);
}
```

## Usage [#usage]

```tsx
import { Select } from "@commenda/meridian/ui/select";

<Select
  label="Company size"
  placeholder="Select a company size"
  options={[{ value: "51-200", label: "51 to 200 employees" }]}
/>;
```

## Single [#single]

The value shows in the field. The placeholder says what to pick.

```tsx
import { Select } from "@commenda/meridian/ui/select";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const SIZES = ["1 to 10", "11 to 50", "51 to 200", "201 to 1,000", "1,000+"].map((s) => ({
	value: s,
	label: `${s} employees`,
}));

export function SelectSingle() {
	return (
		<Fields>
			<Select label="Company size" options={SIZES} placeholder="Select a company size" />
			<Select label="Company size" options={SIZES} defaultValue="51 to 200" />
		</Fields>
	);
}
```

## Leading flag [#leading-flag]

Countries and jurisdictions always lead with their flag. The same flag shows on the row in the list. An empty field shows no flag. Use an icon only for things that are not places.

```tsx
import { Select } from "@commenda/meridian/ui/select";
import { CAFlag, DEFlag, GBFlag, INFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const COUNTRIES = [
	{ value: "US", label: "United States", leadingIcon: <USFlag size={16} /> },
	{ value: "GB", label: "United Kingdom", leadingIcon: <GBFlag size={16} /> },
	{ value: "DE", label: "Germany", leadingIcon: <DEFlag size={16} /> },
	{ value: "IN", label: "India", leadingIcon: <INFlag size={16} /> },
	{ value: "SG", label: "Singapore", leadingIcon: <SGFlag size={16} /> },
	{ value: "CA", label: "Canada", leadingIcon: <CAFlag size={16} /> },
];

export function SelectFlag() {
	return (
		<Fields>
			<Select label="Country" options={COUNTRIES} defaultValue="US" />
			<Select label="Where is your company registered?" options={COUNTRIES} defaultValue="GB" />
		</Fields>
	);
}
```

## Clear [#clear]

clearable adds an x that empties the field. Use it on optional fields only.

```tsx
import { Select } from "@commenda/meridian/ui/select";
import { CAFlag, DEFlag, GBFlag, INFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

const COUNTRIES = [
	{ value: "US", label: "United States", leadingIcon: <USFlag size={16} /> },
	{ value: "GB", label: "United Kingdom", leadingIcon: <GBFlag size={16} /> },
	{ value: "DE", label: "Germany", leadingIcon: <DEFlag size={16} /> },
	{ value: "IN", label: "India", leadingIcon: <INFlag size={16} /> },
	{ value: "SG", label: "Singapore", leadingIcon: <SGFlag size={16} /> },
	{ value: "CA", label: "Canada", leadingIcon: <CAFlag size={16} /> },
];

export function SelectClear() {
	return (
		<Fields>
			<Select
				label="Second country"
				labelConfig={{ optionalLabel: "(optional)" }}
				options={COUNTRIES}
				defaultValue="DE"
				clearConfig={{ label: "Clear second country" }}
			/>
		</Fields>
	);
}
```

## Open [#open]

The list opens 4 below the field and matches its width, with a check on the chosen row. Search turns on past about eight options. Click any field above to open its list.

## States [#states]

Hover from the pointer, open while the list is up (the Input focus look), disabled for values people cannot change. Invalid shows the error under the field.

```tsx
import { Select } from "@commenda/meridian/ui/select";
import { CAFlag, DEFlag, GBFlag, INFlag, SGFlag, USFlag } from "@commenda/pathfinder/flags";
import type { ReactNode } from "react";

function Fields({ children, cols = 2 }: { children: ReactNode; cols?: 2 | 3 }) {
	return (
		<div
			className={`not-prose my-4 grid gap-6 rounded-xl border border-fd-border bg-white p-8 ${
				cols === 3 ? "md:grid-cols-3" : "md:grid-cols-2"
			}`}
		>
			{children}
		</div>
	);
}

/** A form demo with its state name above it, full width so the field keeps its size. */
function Captioned({ label, children }: { label: string; children: ReactNode }) {
	return (
		<div className="flex min-w-0 flex-col gap-2">
			<span className="text-[12px] text-fd-muted-foreground">{label}</span>
			{children}
		</div>
	);
}

const COUNTRIES = [
	{ value: "US", label: "United States", leadingIcon: <USFlag size={16} /> },
	{ value: "GB", label: "United Kingdom", leadingIcon: <GBFlag size={16} /> },
	{ value: "DE", label: "Germany", leadingIcon: <DEFlag size={16} /> },
	{ value: "IN", label: "India", leadingIcon: <INFlag size={16} /> },
	{ value: "SG", label: "Singapore", leadingIcon: <SGFlag size={16} /> },
	{ value: "CA", label: "Canada", leadingIcon: <CAFlag size={16} /> },
];

export function SelectStates() {
	return (
		<Fields cols={3}>
			<Captioned label="default">
				<Select label="Country" options={COUNTRIES} defaultValue="US" />
			</Captioned>
			<Captioned label="disabled">
				<Select
					label="Country"
					options={COUNTRIES}
					defaultValue="US"
					disableConfig={{ isDisabled: true }}
				/>
			</Captioned>
			<Captioned label="invalid">
				<Select
					label="Country"
					options={COUNTRIES}
					placeholder="Select a country"
					errorConfig={{ message: "Choose your country.", reveal: "immediate" }}
				/>
			</Captioned>
		</Fields>
	);
}
```

## Anatomy [#anatomy]

Label row, field, then description or error, exactly as Input. Inside the field: the leading flag (always for countries), the value and the chevron.

| Part | Value |
| --- | --- |
| Field | 40 (`control/xl`), radius 8 |
| Flag | 16 |
| Value | 16 |
| Chevron | 16 |
| Label, description | 14 |

## API reference [#api-reference]

| Prop | Type | Description |
| --- | --- | --- |
| `label` (conditional) | `string` |  |
| `hideLabel` | `boolean` |  |
| `aria-label` (conditional) | `string` | Defines a string value that labels the current element. |
| `required` (conditional) | `true \| false` |  |
| `labelConfig` | `{ optionalLabel: string; help?: never; } \| { help: string; optionalLabel?: never; }` |  |
| `sourceConfig` | `FieldSourceConfig` |  |
| `description` | `string` |  |
| `errorConfig` | `{ message: string; reveal?: "after-blur" \| "immediate"; }` |  |
| `disableConfig` | `DisableConfig` |  |
| `options` (conditional) | `readonly ChoiceOption[]` |  |
| `groups` (conditional) | `readonly ChoiceGroup[]` |  |
| `searchConfig` (conditional) | `{ mode: "local"; enabled?: boolean; placeholder?: string; } \| { mode: "remote"; query: string; onQueryChange: (query: string) => void; resultsQuery: string; isLoading: boolean; error?: string; onRetry?: () => void; placeholder?: string; }` |  |
| `paginationConfig` | `ChoicePaginationConfig` |  |
| `selectedOptions` | `readonly ChoiceOption[]` |  |
| `id` | `string` |  |
| `name` | `string` |  |
| `form` | `string` |  |
| `autoComplete` | `string` |  |
| `className` | `string` |  |
| `placeholder` | `string` |  |
| `onBlur` | `FocusEventHandler<HTMLButtonElement>` |  |
| `onFocus` | `FocusEventHandler<HTMLButtonElement>` |  |
| `clearConfig` | `{ label?: string; }` |  |
| `emptyLabel` | `string` |  |
| `renderConfig` | `{ optionContent?: (option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode; selectedContent?: (option: ChoiceOption) => ReactNode; }` |  |
| `listConfig` | `{ virtualized?: boolean; maxHeight?: number; }` |  |
| `addItemConfig` | `{ label: string; onAddItem: (query: string) => void; isDisabled?: boolean; }` |  |
| `value` (conditional) | `string` |  |
| `onValueChange` (conditional) | `(value: string \| null) => void` |  |
| `defaultValue` | `string` |  |

**`labelConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `optionalLabel` (required) | `string` |  |

Do not supply: `help`.

**`labelConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `help` (required) | `string` |  |

Do not supply: `optionalLabel`.

**`sourceConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `kind` (required) | `"entity" \| "record" \| "document"` |  |
| `label` (required) | `string` |  |
| `preview` (required) | `ReactNode` |  |
| `onOpen` (required) | `() => void` |  |
| `side` | `"top" \| "bottom"` |  |

**`errorConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `message` (required) | `string` |  |
| `reveal` | `"after-blur" \| "immediate"` |  |

**`disableConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `isDisabled` (required) | `boolean` |  |
| `reason` | `string` |  |

**`searchConfig` fields, option 1 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `mode` (required) | `"local"` |  |
| `enabled` | `boolean` |  |
| `placeholder` | `string` |  |

**`searchConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `mode` (required) | `"remote"` |  |
| `query` (required) | `string` |  |
| `onQueryChange` (required) | `(query: string) => void` |  |
| `resultsQuery` (required) | `string` |  |
| `isLoading` (required) | `boolean` |  |
| `error` | `string` |  |
| `onRetry` | `() => void` |  |
| `placeholder` | `string` |  |

**`paginationConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `hasMore` (required) | `boolean` |  |
| `isLoadingMore` (required) | `boolean` |  |
| `onLoadMore` (required) | `() => void` |  |
| `error` | `string` |  |
| `onRetry` | `() => void` |  |

**`clearConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `label` | `string` |  |

**`renderConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `optionContent` | `(option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode` |  |
| `selectedContent` | `(option: ChoiceOption) => ReactNode` |  |

**`listConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `virtualized` | `boolean` |  |
| `maxHeight` | `number` |  |

**`addItemConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `label` (required) | `string` |  |
| `onAddItem` (required) | `(query: string) => void` |  |
| `isDisabled` | `boolean` |  |

## Best practices [#best-practices]

- Use Select to pick from a known list. For free text use Input. For two to five choices that should stay visible, use radios or a SegmentedControl.
- The placeholder says what to pick ("Select a country"), never just "Select".
- Turn on search in the list past about eight options. The country list always has search.
- Countries and jurisdictions always lead with their flag, in the field and on each row in the list. Use an icon only for other kinds of things.
- Match HubSpot: the options are the HubSpot property values, in the same order.
- To pick several values, use Multi-select.
- Source: Pathfinder Select. Meridian makes the field 40 tall with a 16 value, a 14 label and 14 help and error text.
