MultiSelectField

MultiSelectField lets the user pick several values through the Cratis Dropdown. It uses native multiple selection by default and a labeled multi-value combobox when filtering is enabled.

Usage

The excerpt assumes MyCommand is a generated command proxy with the bound properties, and visible / setVisible is component state.

import { CommandDialog } from '@cratis/components/CommandDialog';
import { MultiSelectField } from '@cratis/components/CommandForm';

const categoryOptions = [
    { id: 'finance', label: 'Finance' },
    { id: 'operations', label: 'Operations' },
    { id: 'engineering', label: 'Engineering' },
];

<CommandDialog<MyCommand>
    command={MyCommand}
    title='Edit categories'
    visible={visible}
    onSuccess={() => setVisible(false)}
    onCancel={() => setVisible(false)}
>
    <MultiSelectField<MyCommand>
        value={(c) => c.categories}
        title='Categories'
        options={categoryOptions}
        optionLabel='label'
        optionValue='id'
        placeholder='Select categories'
        filter
    />
</CommandDialog>;

Props

Prop	Type	Default	Description
`value`	`(instance: TCommand) => unknown`	-	Required. Accessor function that returns the bound property from the command instance. Pass the command type as the generic parameter for full type safety.
`options`	`Array<Record<string, unknown>>`	-	Required. Array of option objects.
`optionLabel`	`string`	-	Property name in each option object used as the display text.
`optionValue`	`string`	-	Property name in each option object used as the bound value.
`placeholder`	`string`	-	Placeholder text shown when no options are selected.
`display`	`'comma' \| 'chip'`	-	No effect. See below.
`maxSelectedLabels`	`number`	-	No effect. See below.
`filter`	`boolean`	`false`	Shows a filter input in the options popup.
`showClear`	`boolean`	`false`	Displays a clear icon to reset selected values.
`className`	`string`	-	Extra CSS class combined with the default `w-full`.
`pt`	`DropdownParts`	—	Attributes for the Cratis-owned Dropdown’s stable parts.
`ptOptions` / `unstyled`	—	—	Retained temporarily for source compatibility; ignored.

Every field also accepts Arc’s shared field props, such as title, description, initialValue, and noInitialValue, and the accessibility props id, aria-label, and aria-describedby. See Accessible names and validation errors.

Behavior

Shows an empty array while the bound property is unset. See Field defaults and command values.
The field spans full width within its container.
Validation state is reflected through aria-invalid and data-invalid.