MultiSelect

Multi-value dropdown picker built on Headless UI Listbox in multiple mode. Selected values render as removable chips; the option list is fixed (no text filtering).

When to use

Reach for MultiSelect when the user picks several values from a fixed list and no text filtering is needed.

• Need to filter options by typing? Use MultiCombobox.
• Only one value? Use Select.

Use @uxf/ui/multi-select for a controlled component outside a form. Inside a @uxf/form form, use @uxf/form/multi-select instead — it registers the field with react-hook-form and derives isInvalid / helperText from validation. This @uxf/ui component is the controlled primitive the form twin wraps.

Usage

import { MultiSelect, MultiSelectOption, MultiSelectValue } from "@uxf/ui/multi-select";
import { useState } from "react";

const options: MultiSelectOption<string>[] = [
    { color: "red", id: "one", label: "Option red" },
    { color: "blue", id: "two", label: "Option blue" },
    { disabled: true, id: "three", label: "Option three" },
];

function Example() {
    const [value, setValue] = useState<MultiSelectValue<string>>(null);

    return (
        <MultiSelect
            label="Choose options"
            name="example"
            onChange={setValue}
            options={options}
            placeholder="Select..."
            value={value}
        />
    );
}

value is an array of ids (MultiSelectValue<T> = T[] | null) — not option objects — and onChange receives the new array of ids. Selected chips can be removed with their close button or by pressing Backspace.

Exports: MultiSelect and the types MultiSelectProps, MultiSelectOption, MultiSelectValue, MultiSelectValueId (deprecated alias of SelectableId), MultiSelectTypeRef.

Props

MultiSelectProps<ValueId = SelectableId, Option = MultiSelectOption<ValueId>> extends FormControlProps<ValueId[] | null>. SelectableId is string | number (from @uxf/core/types); MultiSelectOption is { id: ValueId; label: ReactNode; color?: ChipColor; disabled?: boolean }. It is not Clearable — there is no isClearable prop.

The component is a forwardRef — the ref points at the trigger <div> (MultiSelectTypeRef = HTMLDivElement). Layout/dropdown props: className, style, form, leftAddon, rightAddon, leftElement, rightElement, inputArrow, dropdownClassName, dropdownMatchesInputWidth, dropdownMaxHeight (default 240), dropdownPlacement (default "bottom"), dropdownStrategy.

Note: renderOption is present on MultiSelectProps but is not currently wired into the option list — the internal options renderer never forwards it, so options always render option.label (or a checkbox when withCheckboxes). Custom option rendering has no effect today. (In contrast, MultiCombobox does apply renderOption.)

Variants & states

• Checkbox mode: withCheckboxes renders each option as a checkbox and keeps selected options in the list rather than hiding them.
• Chips: each selected value is a Chip; its color comes from the option's color. Chips are removable unless the control or the option is disabled.
• Sizes: small, default, large (via size).
• Invalid / disabled / read-only: as with the other form controls (isInvalid, isDisabled, isReadOnly).
• No search: unlike the combobox family there is no text input; the option list is static.

Requirements

The component composes the input, label, dropdown, form-component, icon, and chip primitives, so import their stylesheets once in your global CSS:

@import url("@uxf/ui/css/icon.css");
@import url("@uxf/ui/css/dropdown.css");
@import url("@uxf/ui/css/label.css");
@import url("@uxf/ui/css/form-component.css");
@import url("@uxf/ui/css/input-basic.css");
@import url("@uxf/ui/css/input.css");
@import url("@uxf/ui/css/chip.css");
@import url("@uxf/ui/css/multi-select.css");

When using withCheckboxes, also import the checkbox stylesheets:

@import url("@uxf/ui/css/checkbox.css");
@import url("@uxf/ui/css/checkbox-input.css");

Also requires the global @uxf/ui token layer, set up once per app — see @uxf/ui setup.