# Multi-select

Page: /docs/components/multi-select

{/* Figma: Meridian → Multi-select (docs 35:92, component set 21:5251). Spec: docs/design-system/meridian/multi-select.md */}

A field for picking several values from a list. The same frame as Select, 40 high with a 16 value and a 14 label, but the picks show as Tags on one line and the list stays open while people tick. On the site it asks where a company sells and which products they want to hear about.

```tsx
import { MultiSelect } from "@commenda/meridian/ui/multi-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 MultiSelectTags() {
	return (
		<Fields>
			<MultiSelect
				label="Where do you sell?"
				options={COUNTRIES}
				defaultValue={["US", "IN", "GB", "DE"]}
				searchConfig={{ mode: "local" }}
			/>
			<MultiSelect label="Where do you sell?" options={COUNTRIES} placeholder="Select countries" />
		</Fields>
	);
}
```

## Usage [#usage]

```tsx
import { MultiSelect } from "@commenda/meridian/ui/multi-select";

<MultiSelect label="Where do you sell?" placeholder="Select countries" options={countries} />;
```

## Tags and +N [#tags-and-n]

Chosen values show as Tags on one line. When they do not fit, the rest collapse into +N, and the full list is in the dropdown. x removes a value without opening the list.

```tsx
import { MultiSelect } from "@commenda/meridian/ui/multi-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 MultiSelectTags() {
	return (
		<Fields>
			<MultiSelect
				label="Where do you sell?"
				options={COUNTRIES}
				defaultValue={["US", "IN", "GB", "DE"]}
				searchConfig={{ mode: "local" }}
			/>
			<MultiSelect label="Where do you sell?" options={COUNTRIES} placeholder="Select countries" />
		</Fields>
	);
}
```

## Open [#open]

The list opens 4 below the field and matches its width. It stays open while people tick, rows never reorder, and search turns on past about eight options. Click a field above to try it.

## 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 { MultiSelect } from "@commenda/meridian/ui/multi-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 MultiSelectStates() {
	return (
		<Fields cols={3}>
			<Captioned label="default">
				<MultiSelect label="Where do you sell?" options={COUNTRIES} defaultValue={["US", "IN"]} />
			</Captioned>
			<Captioned label="disabled">
				<MultiSelect
					label="Where do you sell?"
					options={COUNTRIES}
					defaultValue={["US", "IN"]}
					disableConfig={{ isDisabled: true }}
				/>
			</Captioned>
			<Captioned label="invalid">
				<MultiSelect
					label="Where do you sell?"
					options={COUNTRIES}
					placeholder="Select countries"
					errorConfig={{ message: "Choose at least one country.", reveal: "immediate" }}
				/>
			</Captioned>
		</Fields>
	);
}
```

## Anatomy [#anatomy]

Label row, field, then description or error, exactly as Input. Inside the field: the Tags (each country with its flag), +N when they overflow, and the chevron.

| Part | Value |
| --- | --- |
| Field | 40 (`control/xl`), radius 8 |
| Tags | Tag sm 20 |
| 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; }` |  |
| `selectionDisplayConfig` | `{ mode: "tags"; } \| { mode: "summary"; format: (count: number) => string; }` |  |
| `selectAllConfig` | `{ label?: string; }` |  |
| `selectionLimitConfig` | `{ max: number; message?: string; }` |  |
| `value` (conditional) | `readonly string[]` |  |
| `onValueChange` (conditional) | `(value: readonly string[]) => void` |  |
| `defaultValue` | `readonly 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` |  |

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

| Field | Type | Description |
| --- | --- | --- |
| `mode` (required) | `"tags"` |  |

**`selectionDisplayConfig` fields, option 2 of 2**

| Field | Type | Description |
| --- | --- | --- |
| `mode` (required) | `"summary"` |  |
| `format` (required) | `(count: number) => string` |  |

**`selectAllConfig` fields**

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

**`selectionLimitConfig` fields**

| Field | Type | Description |
| --- | --- | --- |
| `max` (required) | `number` |  |
| `message` | `string` |  |

## Best practices [#best-practices]

- Use Multi-select to pick several values from a known list. For one value use Select.
- Tags stay on one line. When they do not fit, the rest become +N, and the full selection is in the list.
- Use a summary ("3 countries selected") instead of Tags when the selection is listed elsewhere on the page.
- Turn on search in the list past about eight options, and offer Select all for long lists.
- Countries lead with their flag on each Tag and on each row in the list.
- On HubSpot forms it maps to a multiple-checkbox property. Keep the option labels the same as HubSpot.
- Source: Pathfinder Multi-select. Meridian makes the field 40 tall with a 16 value and a 14 label; the Tags inside are size sm 20.
