Skip to main content

MultiSelect

Choose multiple collection items in a searchable tag field.

Design+1
Props
Slots

Anatomy#

MultiSelect [component; no DOM]
├── control [slot]
│   ├── leading [slot]
│   ├── tagsContainer [slot]
│   │   ├── tag [slot]
│   │   │   ├── tagLabel [slot]
│   │   │   └── tagRemove [slot]
│   │   ├── tagOverflow [slot]
│   │   └── input [slot]
│   ├── clear [slot]
│   └── trigger [slot]
└── positioner [internal]
    └── content [slot]
        ├── listbox [slot]
        │   ├── group [slot]
        │   │   └── groupLabel [slot]
        │   ├── separator [slot]
        │   └── item [slot]
        │       ├── itemLeading [slot]
        │       ├── itemWrapper [slot]
        │       │   ├── itemLabel [slot]
        │       │   └── itemDescription [slot]
        │       └── itemIndicator [slot]
        └── empty [slot]

MultiSelect renders its portaled popup internally; the popup names are style slots, not attached parts. Replace tags with tagRender.

Usage#

Use MultiSelect for several collection items shown as tags, or for creatable free-form tags. Each value resolves through a collection item. Use Select for one non-editable choice, Combobox for editable single selection, or BaseSelect to compose the listbox yourself. Unlike Select and Combobox, items takes item objects only, with no string shorthand.

import { Field, MultiSelect } from 'moraine'

export function Example() {
  return (
    <Field label="Skills">
      <MultiSelect
        items={[
          { label: 'Design', value: 'design' },
          { label: 'Code', value: 'code' },
        ]}
        placeholder="Choose skills"
      />
    </Field>
  )
}

Values and tag lifecycle#

value is the array of selected item values, in selection order. An empty array means no selection, and an empty string can be an item value. Pair value with onValueChange for controlled selection, or use defaultValue for an initial uncontrolled selection. onValueChange receives the full new array and clears the search text afterward. Without searchable, printable keys trigger collection typeahead. Set searchable to let users type in the field to filter options.

<MultiSelect
  searchable
  items={frameworks}
  value={selected()}
  onValueChange={setSelected}
  clearable
/>

clearable shows a clear button while there are selected values or search text. It does not always empty a MultiSelect: selected values whose items are disabled stay selected because the user cannot remove them, and values that match no item are dropped. Every other selection is cleared, the search text is emptied, and onClear runs after onValueChange. Select and Combobox clear to an empty value instead.

Search and item creation#

searchable and createItem decide whether the field is editable. Filtering follows editability, so the four combinations behave as follows:

searchable createItem Field Filters options Creates items openOnControlClick default
unset unset Trigger button, no text input No No true
true unset Editable input Yes No false
unset set Editable input Yes Yes false
true set Editable input Yes Yes false

searchable alone filters the collection as the user types. createItem makes the input editable and enables creation. It also filters the list, so searchable adds nothing once createItem is set. filterMethod and autocomplete have no effect on a non-editable control.

openOnControlClick defaults to the opposite of editability. A non-editable control opens its popup on click. An editable control focuses its input on click and opens from typing, the chevron button, or ArrowDown. Set openOnControlClick explicitly to change either default.

Item creation and delimiters#

createItem receives the trimmed query text when the user commits text that matches no existing item by label or value, and returns the TItem to select. The item is added to the top of the option list until a native form reset. Nothing is created when the value is already selected or maxValues is reached. Commit text with Enter, a token separator, or paste; all go through the same creation path. tokenSeparators defaults to [','].

<MultiSelect
  value={tags()}
  onValueChange={setTags}
  createItem={(input) => ({ label: input.trim(), value: input.trim().toLowerCase() })}
  tokenSeparators={[',', ' ']}
/>

Keyboard interaction#

Key Behavior
Backspace With an empty input, remove the last removable tag
ArrowLeft At the start of the input, focus the last tag’s remove button
ArrowLeft / Right On a remove button, focus the neighboring removable tag, or return to the input
Backspace / Delete On a remove button, remove that tag and focus a neighbor
ArrowDown / ArrowUp Open the popup and move the highlight through enabled options
Enter Commit the highlighted option, or create an item from the input text
Escape Close the popup; the search text resets once it closes
Tab Close the popup and move focus on

Virtualization#

Pass a virtualizer from createListVirtualizer when rendering the full collection makes opening or scrolling slow. Type it over MultiSelectT.Row. Read the Virtualization guide for setup, row measurement, stable keys, and keyboard navigation.

<MultiSelect items={items} virtualizer={virtualizer} />

Examples#

Color issue labels#

Use tagRender to style tags from item data such as a color class. Selected values still come from the collection.

import { Icon, MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'

interface LabelItem extends MultiSelectT.Item {
  color: string
}

const LABELS: LabelItem[] = [
  {
    label: 'bug',
    value: 'bug',
    color: 'bg-red-500/15 border-red-500/30 text-red-700 dark:text-red-400',
  },
  {
    label: 'feature',
    value: 'feature',
    color: 'bg-purple-500/15 border-purple-500/30 text-purple-700 dark:text-purple-400',
  },
  {
    label: 'documentation',
    value: 'docs',
    color: 'bg-blue-500/15 border-blue-500/30 text-blue-700 dark:text-blue-400',
  },
  {
    label: 'performance',
    value: 'perf',
    color: 'bg-amber-500/15 border-amber-500/30 text-amber-700 dark:text-amber-400',
  },
  {
    label: 'security',
    value: 'security',
    color: 'bg-emerald-500/15 border-emerald-500/30 text-emerald-700 dark:text-emerald-400',
  },
]

export function CustomTags() {
  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Issue Labels</label>
      <MultiSelect<LabelItem>
        items={LABELS}
        defaultValue={['bug', 'perf']}
        searchable
        openOnControlClick
        placeholder="Select labels..."
        tagRender={(props) => {
          const color = () => props.item?.color ?? 'bg-muted border-border text-foreground'
          return (
            <span
              class={`text-xs font-medium px-2 py-0.5 border rounded-full inline-flex gap-1.5 items-center ${color()}`}
            >
              <span class="rounded-full bg-current opacity-70 h-1.5 w-1.5" />
              <span>{props.label}</span>
              <button
                type="button"
                aria-label={`Remove ${props.value}`}
                onClick={(event) => {
                  event.stopPropagation()
                  props.remove()
                }}
                class="p-0.5 rounded-full inline-flex transition-opacity items-center justify-center hover:opacity-80"
              >
                <Icon name="i-lucide:x" class="size-3" />
              </button>
            </span>
          )
        }}
      />
    </div>
  )
}

Assign project members#

Search teammates and keep each selection as a tag. Put the email or role in description.

import { MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'

const TEAM_MEMBERS: MultiSelectT.Item[] = [
  {
    label: 'Sarah Connor',
    value: 'sarah',
    icon: 'i-lucide:user',
    description: '[email protected] · Admin',
  },
  {
    label: 'Alex Rivera',
    value: 'alex',
    icon: 'i-lucide:user',
    description: '[email protected] · Designer',
  },
  {
    label: 'Elena Rostova',
    value: 'elena',
    icon: 'i-lucide:user',
    description: '[email protected] · Engineer',
  },
  {
    label: 'David Kim',
    value: 'david',
    icon: 'i-lucide:user',
    description: '[email protected] · DevOps',
  },
  {
    label: 'Marcus Vance',
    value: 'marcus',
    icon: 'i-lucide:user',
    description: '[email protected] · QA',
  },
]

export function UserChips() {
  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Project Assignees</label>
      <MultiSelect
        items={TEAM_MEMBERS}
        defaultValue={['sarah', 'alex']}
        searchable
        openOnControlClick
        placeholder="Assign teammates..."
        clearable
      />
    </div>
  )
}

Cap selection and visible tags#

maxValues blocks additional selections by disabling unselected options. maxVisible is visual: surplus selections stay committed and collapse into a +N summary. Use tagOverflowRender to render the hidden tags yourself, for example in a tooltip.

import { Icon, MultiSelect, Tooltip } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { For } from 'solid-js'

const TECH_STACK: MultiSelectT.Item[] = [
  { label: 'SolidJS', value: 'solid', icon: 'i-lucide:atom' },
  { label: 'TypeScript', value: 'ts', icon: 'i-lucide:code' },
  { label: 'Tailwind CSS', value: 'tailwind', icon: 'i-lucide:palette' },
  { label: 'Rust', value: 'rust', icon: 'i-lucide:cog' },
  { label: 'Docker', value: 'docker', icon: 'i-lucide:container' },
]

export function MaxValuesMaxVisible() {
  return (
    <div class="gap-6 grid max-w-2xl w-full sm:grid-cols-2">
      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Selection Limit (maxValues = 2)
        </label>
        <MultiSelect
          items={TECH_STACK}
          maxValues={2}
          placeholder="Select up to 2 skills..."
          defaultValue={['solid']}
          searchable
          openOnControlClick
        />
        <p class="text-xs text-muted-foreground">
          Hard cap: prevents adding more once limit is reached.
        </p>
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Display Limit (maxVisible = 1)
        </label>
        <MultiSelect
          items={TECH_STACK}
          defaultValue={['solid', 'ts', 'tailwind']}
          maxVisible={1}
          tagOverflowRender={(props) => (
            <Tooltip openDelay={200}>
              <Tooltip.Trigger
                as="span"
                class="text-muted-foreground px-1 flex cursor-default items-center"
              >
                +{props.count}
              </Tooltip.Trigger>
              <Tooltip.Content class="p-2 flex gap-1">
                <For each={props.tags}>
                  {(tag) => (
                    <span class="px-2 py-1 rounded bg-muted flex gap-1.5 items-center">
                      {tag.label}
                      <Icon name="i-lucide:x" class="text-muted-foreground size-3.5" />
                    </span>
                  )}
                </For>
              </Tooltip.Content>
            </Tooltip>
          )}
          placeholder="Select tags..."
          searchable
          openOnControlClick
        />
        <p class="text-xs text-muted-foreground">
          Visual only: hover +N to inspect the collapsed tags.
        </p>
      </div>
    </div>
  )
}

Create a missing topic#

Pass createItem and an emptyRender action so unmatched text can become a collection item. The create function in the emptyRender state runs createItem for the current search text.

import { Button, MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createSignal } from 'solid-js'

const INITIAL_TOPICS: MultiSelectT.Item[] = [
  { label: 'React', value: 'react' },
  { label: 'SolidJS', value: 'solid' },
  { label: 'Vue.js', value: 'vue' },
  { label: 'TypeScript', value: 'ts' },
]

export function CreateNewTags() {
  const [tags, setTags] = createSignal<MultiSelectT.Item['value'][]>(['solid'])

  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">
        Topics (Select existing or type to create)
      </label>
      <MultiSelect
        searchable
        items={INITIAL_TOPICS}
        value={tags()}
        onValueChange={setTags}
        createItem={(input) => ({ value: input.trim().toLowerCase(), label: input.trim() })}
        tokenSeparators={[',', ';']}
        placeholder="Type to create or select..."
        openOnControlClick
        clearable
        emptyRender={(ctx) => (
          <div class="p-2 text-center">
            <Button
              variant="link"
              size="sm"
              class="text-xs text-primary"
              onClick={() => ctx.create()}
            >
              Create &ldquo;{ctx.searchValue}&rdquo;
            </Button>
          </div>
        )}
      />
      <p class="text-xs text-muted-foreground">Selected values: {tags().join(', ') || 'none'}</p>
    </div>
  )
}

Enter free-form tags#

With no predefined items, combine createItem and tokenSeparators for a tag input. Comma, space, and paste all create tokens.

import { MultiSelect } from 'moraine'
import { createSignal } from 'solid-js'

export function FreeFormTags() {
  const [tags, setTags] = createSignal<string[]>(['web', 'ui', 'components'])

  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">
        Free-Form Tags (Comma or space separated)
      </label>
      <MultiSelect
        value={tags()}
        onValueChange={setTags}
        createItem={(input) => ({ value: input.trim().toLowerCase(), label: input.trim() })}
        tokenSeparators={[',', ' ']}
        placeholder="Type words, press space or comma..."
        clearable
      />
      <p class="text-xs text-muted-foreground">Tags array: {JSON.stringify(tags())}</p>
    </div>
  )
}

Grant grouped permissions#

Organize a large permission set with type: 'group'. Group labels are not selectable.

import { MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createSignal } from 'solid-js'

const PERMISSION_GROUPS: MultiSelectT.Entry[] = [
  {
    label: 'User Management',
    type: 'group',
    items: [
      { label: 'Invite Members', value: 'users:invite', icon: 'i-lucide:user-plus' },
      { label: 'Edit Roles', value: 'users:roles', icon: 'i-lucide:shield' },
      { label: 'Remove Members', value: 'users:remove', icon: 'i-lucide:user-minus' },
    ],
  },
  {
    label: 'Content Management',
    type: 'group',
    items: [
      { label: 'Create Articles', value: 'content:create', icon: 'i-lucide:file-plus' },
      { label: 'Publish Content', value: 'content:publish', icon: 'i-lucide:send' },
      { label: 'Delete Content', value: 'content:delete', icon: 'i-lucide:trash-2' },
    ],
  },
  {
    label: 'Billing & Settings',
    type: 'group',
    items: [
      { label: 'View Invoices', value: 'billing:view', icon: 'i-lucide:receipt' },
      { label: 'Modify Subscriptions', value: 'billing:edit', icon: 'i-lucide:credit-card' },
    ],
  },
]

export function GroupedItems() {
  const [selected, setSelected] = createSignal(['users:invite', 'content:publish'])

  return (
    <div class="max-w-md w-full space-y-2">
      <label class="text-xs text-muted-foreground font-medium block">Role Permissions</label>
      <MultiSelect
        placeholder="Select permissions..."
        items={PERMISSION_GROUPS}
        value={selected()}
        onValueChange={setSelected}
        searchable
        openOnControlClick
        clearable
      />
    </div>
  )
}

Lock required modules#

Disable an option to keep it in the list without allowing toggle. disabled and readOnly on the root freeze the whole control.

import { MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'

const MODULES: MultiSelectT.Item[] = [
  { label: 'Core Runtime (Locked)', value: 'core', disabled: true },
  { label: 'Analytics Engine', value: 'analytics' },
  { label: 'Push Notifications', value: 'notifications' },
  { label: 'Search Indexer', value: 'search' },
]

export function ClearAndDisabled() {
  return (
    <div class="max-w-md w-full space-y-4">
      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">
          Disabled Option inside List (Core Runtime cannot be toggled)
        </label>
        <MultiSelect
          items={MODULES}
          defaultValue={['core', 'analytics']}
          searchable
          openOnControlClick
          placeholder="Select optional modules..."
        />
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">Disabled Component</label>
        <MultiSelect
          items={MODULES}
          disabled
          defaultValue={['analytics', 'search']}
          placeholder="Disabled"
        />
      </div>

      <div class="space-y-1.5">
        <label class="text-xs text-muted-foreground font-medium block">Read-only Component</label>
        <MultiSelect
          items={MODULES}
          readOnly
          defaultValue={['core', 'notifications']}
          placeholder="Read-only"
        />
      </div>
    </div>
  )
}

Search a large collection#

Pass a createListVirtualizer instance as virtualizer when opening or scrolling the full list is slow.

import { MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createListVirtualizer } from 'moraine/virtualizer'

const OPTIONS: MultiSelectT.Item<string>[] = Array.from({ length: 10_000 }, (_, index) => ({
  value: `option-${index}`,
  label: `Option ${index + 1}`,
}))

export function Virtualization() {
  const virtualizer = createListVirtualizer<MultiSelectT.Row<MultiSelectT.Item<string>>>({
    estimateSize: (entry) => (entry.type === 'label' ? 30 : 32),
    getItemKey: (entry) => entry.key,
    overscan: 8,
  })

  return (
    <div class="max-w-md w-full">
      <MultiSelect
        items={OPTIONS}
        searchable
        openOnControlClick
        placeholder="Search across 10,000 options..."
        virtualizer={virtualizer}
        classes={{ listbox: 'h-80 max-h-80' }}
      />
    </div>
  )
}

Require a minimum number of tags#

Validate the selected array with createForm. Use a minLength schema rule to fail short selections; required only checks that something is selected. A selection made only of disabled items passes constraint validation but submits no value to the native form, as a native <select multiple> does.

import { Button, createForm, MultiSelect } from 'moraine'
import type { MultiSelectT } from 'moraine'
import { createSignal } from 'solid-js'
import * as v from 'valibot'

const TOPICS = [
  { label: 'TypeScript', value: 'typescript' },
  { label: 'SolidJS', value: 'solidjs' },
  { label: 'Tailwind CSS', value: 'tailwind' },
  { label: 'UnoCSS', value: 'unocss' },
  { label: 'Vite', value: 'vite' },
] satisfies MultiSelectT.Item[]

export function FormIntegration() {
  const [submittedTags, setSubmittedTags] = createSignal<string[]>([])
  const form = createForm({
    schema: v.object({
      topics: v.pipe(
        v.array(v.string()),
        v.minLength(2, 'Please select at least 2 relevant topics.'),
      ),
    }),
    initialInput: { topics: ['typescript'] },
    validate: 'input',
  })

  return (
    <form.Form onSubmit={(output) => setSubmittedTags(output.topics)}>
      <div class="max-w-xl space-y-4">
        <form.Field
          name="topics"
          label="Interest Topics"
          description="Select at least 2 topics for your curated developer feed."
          required
        >
          <MultiSelect
            items={TOPICS}
            placeholder="Select topics..."
            searchable
            openOnControlClick
            clearable
          />
        </form.Field>
        <div class="flex gap-3 items-center">
          <Button type="submit" variant="soft" tone="neutral" size="sm">
            Validate
          </Button>
          <p class="text-xs text-muted-foreground">
            Submitted:{' '}
            <span class="text-foreground font-medium font-mono">
              {submittedTags().length ? submittedTags().join(', ') : 'none'}
            </span>
          </p>
        </div>
      </div>
    </form.Form>
  )
}

API Reference#

Attributes#

Attributes
data-closed
Slot: multi-select-controlmulti-select-contentmulti-select-trigger
Description: Present when disclosure or transition content is closed.
data-disabled
Slot: multi-select-controlmulti-select-itemmulti-select-trigger
Description: Present when the component, slot, or item is disabled.
data-editable
Slot: multi-select-control
Description: Present when the value can be edited as text.
data-expanded
Slot: multi-select-controlmulti-select-contentmulti-select-trigger
Description: Present when the panel, accordion, or menu is expanded.
data-invalid
Slot: multi-select-controlmulti-select-trigger
Description: Present when the field or form has a validation error.
data-readonly
Slot: multi-select-control
Description: Present when the field is in read-only mode.
data-required
Slot: multi-select-control
Description: Present when the field input is required.
data-tags
Slot: multi-select-control
Description: Present when the control is displaying selected values as tags.
data-side
Slot: multi-select-content
Description: Stores the resolved floating or drawer content side.
data-highlighted
Slot: multi-select-itemmulti-select-item-description
Description: Present when the item is highlighted by pointer or keyboard navigation.
data-selected
Slot: multi-select-item
Description: Present when the item or tab is selected.
data-duplicate
Slot: multi-select-input
Description: Present when the entered value duplicates an existing value.
data-loading
Slot: multi-select-trigger
Description: Present when the component or async operation is loading.

Props#

Renders a <div> element by default.

Prop