Meridianby Commenda
Components

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.

United States, India, United Kingdom, Germany

Usage

Example.tsx
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.

United States, India, United Kingdom, Germany

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.

default
United States, India
disabled
United States, India
invalid
Choose at least one country.

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.

PartValue
Field40 (control/xl), radius 8
TagsTag sm 20
Label, description14

API reference

PropTypeDescription
labelConditionalstringFrom Pathfinder.
hideLabelbooleanFrom Pathfinder.
aria-labelConditionalstringDefines a string value that labels the current element.
requiredConditionaltrue | falseFrom Pathfinder.
labelConfigObjectView fields · 2 shapesFrom Pathfinder.
sourceConfigFieldSourceConfigView fieldsFrom Pathfinder.
descriptionstringFrom Pathfinder.
errorConfigObjectView fieldsFrom Pathfinder.
disableConfigDisableConfigView fieldsFrom Pathfinder.
optionsConditionalreadonly ChoiceOption[]From Pathfinder.
groupsConditionalreadonly ChoiceGroup[]From Pathfinder.
searchConfigConditionalObjectView fields · 2 shapesFrom Pathfinder.
paginationConfigChoicePaginationConfigView fieldsFrom Pathfinder.
selectedOptionsreadonly ChoiceOption[]From Pathfinder.
idstringFrom Pathfinder.
namestringFrom Pathfinder.
formstringFrom Pathfinder.
autoCompletestringFrom Pathfinder.
classNamestringFrom Pathfinder.
placeholderstringFrom Pathfinder.
onBlurFocusEventHandler<HTMLButtonElement>From Pathfinder.
onFocusFocusEventHandler<HTMLButtonElement>From Pathfinder.
clearConfigObjectView fieldsFrom Pathfinder.
emptyLabelstringFrom Pathfinder.
renderConfigObjectView fieldsFrom Pathfinder.
listConfigObjectView fieldsFrom Pathfinder.
addItemConfigObjectView fieldsFrom Pathfinder.
selectionDisplayConfigObjectView fields · 2 shapesFrom Pathfinder.
selectAllConfigObjectView fieldsFrom Pathfinder.
selectionLimitConfigObjectView fieldsFrom Pathfinder.
valueConditionalreadonly string[]From Pathfinder.
onValueChangeConditional(value: readonly string[]) => voidFrom Pathfinder.
defaultValuereadonly string[]From Pathfinder.
labelConfigObject fields

Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.

Option 1

FieldTypeDescription
optionalLabelRequiredstring

Do not supply: help.

Option 2

FieldTypeDescription
helpRequiredstring

Do not supply: optionalLabel.

sourceConfigObject fields
FieldTypeDescription
kindRequired"entity" | "record" | "document"
labelRequiredstring
previewRequiredReactNode
onOpenRequired() => void
side"top" | "bottom"
errorConfigObject fields
FieldTypeDescription
messageRequiredstring
reveal"after-blur" | "immediate"
disableConfigObject fields
FieldTypeDescription
isDisabledRequiredboolean
reasonstring
searchConfigObject fields

Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.

Option 1

FieldTypeDescription
modeRequired"local"
enabledboolean
placeholderstring

Option 2

FieldTypeDescription
modeRequired"remote"
queryRequiredstring
onQueryChangeRequired(query: string) => void
resultsQueryRequiredstring
isLoadingRequiredboolean
errorstring
onRetry() => void
placeholderstring
paginationConfigObject fields
FieldTypeDescription
hasMoreRequiredboolean
isLoadingMoreRequiredboolean
onLoadMoreRequired() => void
errorstring
onRetry() => void
clearConfigObject fields
FieldTypeDescription
labelstring
renderConfigObject fields
FieldTypeDescription
optionContent(option: ChoiceOption, state: { isSelected: boolean; }) => ReactNode
selectedContent(option: ChoiceOption) => ReactNode
listConfigObject fields
FieldTypeDescription
virtualizedboolean
maxHeightnumber
addItemConfigObject fields
FieldTypeDescription
labelRequiredstring
onAddItemRequired(query: string) => void
isDisabledboolean
selectionDisplayConfigObject fields

Choose one of these 2 shapes. Don't combine fields the chosen shape excludes.

Option 1

FieldTypeDescription
modeRequired"tags"

Option 2

FieldTypeDescription
modeRequired"summary"
formatRequired(count: number) => string
selectAllConfigObject fields
FieldTypeDescription
labelstring
selectionLimitConfigObject fields
FieldTypeDescription
maxRequirednumber
messagestring

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.

On this page