Forms

MultiSelect

Multi-value dropdown with checkbox options, optional filtering, and count-summary trigger text.

import { MultiSelect } from '@lostgradient/cinder/multi-select';
formselectionmultiselect
01

Overview

Multi-value dropdown that presents checkbox options inside an anchored floating list.

Usage

svelte 
<script lang="ts">
  import MultiSelect from '@lostgradient/cinder/multi-select';
</script>

<MultiSelect />
Live preview
02

When to use

Use when
  • Selecting multiple values from a fixed option list while preserving compact form layout.
  • Showing many options in an anchored picker instead of a permanently-expanded checkbox group.
Avoid when
  • Selecting a single value from a short fixed list — use select instead.
  • Moving items between available/selected panes — use transfer-list instead.
03

Examples

Basic multi-select

Pick multiple values and show the selected count on the trigger.

Filterable with warning

Enable filtering, warning helper text, and top-after-reopen selection feedback.

04

Props

Props for multi-select
Name Type Default Required Bindable Description
id text req Unique identifier — required for label association and ARIA wiring.
items readonly MultiSelectItem<T>[] req Full option set. The sole inference source for T.
selectedIds NoInfer<T>[] bind Bindable selected IDs.
name text Native form field name. Emits one hidden input per selected id.
label text Visible label rendered in a <label> associated via for.
placeholder text 'Select options' Placeholder text when nothing is selected.
description text Helper text displayed below the trigger; wired via aria-describedby.
error text Validation error message; sets aria-invalid="true".
warning text Warning text rendered below the control and included in aria-describedby.
disabled boolean Disables the control. Inherited from a wrapping FormField when unset.
readonly boolean false Prevents changing selection while still allowing viewing current selections.
required boolean Marks the field required and shows the required marker on the label.
filterable boolean false Enables the filter input rendered above the options list.
filter (item: MultiSelectItem<T>, query: string) => boolean Custom option filter callback. Defaults to case-insensitive label/description matching.
selectionFeedback 'top' | 'fixed' | 'top-after-reopen' 'fixed' Selected-option ordering behavior when the menu is open.
direction 'down' | 'up' 'down' Open direction for the floating panel.