intro

MultiSelect

A complex organism for selecting multiple options via chips.

MultiSelect

The MultiSelect component combines a search input with a dropdown list of options to allow users to select multiple items. Selected items are displayed as removable badges (chips) within the input area. It relies heavily on composition, utilizing native input elements, the Checkbox atom, and the Badge atom to adhere to the Curva & Concreto doctrine.

Basic MultiSelect

Select Regions

function helper($$renderer) { $$renderer.push(`Select the states for the new policy coverage.`); }

Current Value: rj

Searchable MultiSelect

Searchable Regions

function helper($$renderer) { $$renderer.push(`Type to filter the ${$.escape(states.length)} available states.`); }

Current Value: None selected

Validation State

Restricted Regions

function error($$renderer) { $$renderer.push(`These regions cannot be selected together under current legislation.`); }

Disabled State

Historical Record

function helper($$renderer) { $$renderer.push(`Historical selections cannot be altered.`); }

Usage

The MultiSelect is designed to be composed within a FormField component. It automatically inherits the id, aria-describedby, and invalid state via context.

<script>
  import { FormField, MultiSelect } from 'cobogo';

  let selectedStates = $state([]);
  const states = [
    { value: 'sp', label: 'São Paulo' },
    { value: 'rj', label: 'Rio de Janeiro' },
    { value: 'mg', label: 'Minas Gerais' },
    // ...
  ];
</script>

<FormField id="states-multi" label="Select States">
  <MultiSelect
    options={states}
    bind:value={selectedStates}
    placeholder="Select multiple..."
    searchable
  />
  {#snippet helper()}
    <p>Select all states that apply to this region.</p>
  {/snippet}
</FormField>

Props

Prop	Type	Default	Description
`value`	`string[]`	`[]`	The array of currently selected option values.
`options`	`Array<{value: string, label: string}>`	`[]`	Available options to choose from.
`placeholder`	`string`	`'Selecione...'`	Placeholder text when no options are selected.
`searchable`	`boolean`	`false`	Enables the text input to filter the options list.
`disabled`	`boolean`	`false`	Disables the component.
`invalid`	`boolean`	`false`	Triggers the invalid/error state. Usually inherited from `FormField`.

Variants

Searchable vs Basic

By default, the MultiSelect operates as a standard dropdown. Passing the searchable prop enables a text input that filters the available options.

<!-- Basic Dropdown -->
<MultiSelect options={opts} bind:value={val} />

<!-- Searchable Filter -->
<MultiSelect options={opts} bind:value={val} searchable placeholder="Search..." />

Invalid State

The invalid state overrides the standard background with var(--vermelho-soft) and highlights borders in var(--vermelho), following the global error aesthetic.

<FormField id="multi-err" label="Categories" invalid>
  <MultiSelect options={opts} bind:value={val} />
  {#snippet error()}
    <p>You must select at least one category.</p>
  {/snippet}
</FormField>

Accessibility

The trigger element functions as a role="combobox" controlling a role="listbox".
Keyboard navigation provides full access: Enter or Space opens the menu, ArrowDown opens and focuses the list, and Escape closes it.
Selected option badges include aria-label="Remove [Option Name]" on their removal buttons.
The hidden input correctly syncs aria-invalid from the FormField context.
Native tabindex management ensures focus is trapped appropriately when the dropdown is open.