Multi-select
Pick several values from a list.
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.
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
import { MultiSelect } from "@commenda/meridian/ui/multi-select";
<MultiSelect label="Where do you sell?" placeholder="Select countries" options={countries} />;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.
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
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
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.
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
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
| Prop | Type | Description |
|---|---|---|
labelConditional | string | From Pathfinder. |
hideLabel | boolean | From Pathfinder. |
aria-labelConditional | string | Defines a string value that labels the current element. |
requiredConditional | true | false | From Pathfinder. |
labelConfig | ObjectView fields · 2 shapes | From Pathfinder. |
sourceConfig | FieldSourceConfigView fields | From Pathfinder. |
description | string | From Pathfinder. |
errorConfig | ObjectView fields | From Pathfinder. |
disableConfig | DisableConfigView fields | From Pathfinder. |
optionsConditional | readonly ChoiceOption[] | From Pathfinder. |
groupsConditional | readonly ChoiceGroup[] | From Pathfinder. |
searchConfigConditional | ObjectView fields · 2 shapes | From Pathfinder. |
paginationConfig | ChoicePaginationConfigView fields | From Pathfinder. |
selectedOptions | readonly ChoiceOption[] | From Pathfinder. |
id | string | From Pathfinder. |
name | string | From Pathfinder. |
form | string | From Pathfinder. |
autoComplete | string | From Pathfinder. |
className | string | From Pathfinder. |
placeholder | string | From Pathfinder. |
onBlur | FocusEventHandler<HTMLButtonElement> | From Pathfinder. |
onFocus | FocusEventHandler<HTMLButtonElement> | From Pathfinder. |
clearConfig | ObjectView fields | From Pathfinder. |
emptyLabel | string | From Pathfinder. |
renderConfig | ObjectView fields | From Pathfinder. |
listConfig | ObjectView fields | From Pathfinder. |
addItemConfig | ObjectView fields | From Pathfinder. |
selectionDisplayConfig | ObjectView fields · 2 shapes | From Pathfinder. |
selectAllConfig | ObjectView fields | From Pathfinder. |
selectionLimitConfig | ObjectView fields | From Pathfinder. |
valueConditional | readonly string[] | From Pathfinder. |
onValueChangeConditional | (value: readonly string[]) => void | From Pathfinder. |
defaultValue | readonly string[] | From Pathfinder. |
labelConfigObject fields
Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.
Option 1
| Field | Type | Description |
|---|---|---|
optionalLabelRequired | string |
Do not supply: help.
Option 2
| Field | Type | Description |
|---|---|---|
helpRequired | string |
Do not supply: optionalLabel.
sourceConfigObject fields
| Field | Type | Description |
|---|---|---|
kindRequired | "entity" | "record" | "document" | |
labelRequired | string | |
previewRequired | ReactNode | |
onOpenRequired | () => void | |
side | "top" | "bottom" |
errorConfigObject fields
| Field | Type | Description |
|---|---|---|
messageRequired | string | |
reveal | "after-blur" | "immediate" |
disableConfigObject fields
| Field | Type | Description |
|---|---|---|
isDisabledRequired | boolean | |
reason | string |
searchConfigObject fields
Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.
Option 1
| Field | Type | Description |
|---|---|---|
modeRequired | "local" | |
enabled | boolean | |
placeholder | string |
Option 2
| Field | Type | Description |
|---|---|---|
modeRequired | "remote" | |
queryRequired | string | |
onQueryChangeRequired | (query: string) => void | |
resultsQueryRequired | string | |
isLoadingRequired | boolean | |
error | string | |
onRetry | () => void | |
placeholder | string |
paginationConfigObject fields
| Field | Type | Description |
|---|---|---|
hasMoreRequired | boolean | |
isLoadingMoreRequired | boolean | |
onLoadMoreRequired | () => void | |
error | string | |
onRetry | () => void |
clearConfigObject fields
| Field | Type | Description |
|---|---|---|
label | string |
renderConfigObject fields
| Field | Type | Description |
|---|---|---|
optionContent | (option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode | |
selectedContent | (option: ChoiceOption) => ReactNode |
listConfigObject fields
| Field | Type | Description |
|---|---|---|
virtualized | boolean | |
maxHeight | number |
addItemConfigObject fields
| Field | Type | Description |
|---|---|---|
labelRequired | string | |
onAddItemRequired | (query: string) => void | |
isDisabled | boolean |
selectionDisplayConfigObject fields
Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.
Option 1
| Field | Type | Description |
|---|---|---|
modeRequired | "tags" |
Option 2
| Field | Type | Description |
|---|---|---|
modeRequired | "summary" | |
formatRequired | (count: number) => string |
selectAllConfigObject fields
| Field | Type | Description |
|---|---|---|
label | string |
selectionLimitConfigObject fields
| Field | Type | Description |
|---|---|---|
maxRequired | number | |
message | string |
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.