MultiSelect

HTML

<div class="corn-multi-select">
  <div class="corn-pills-input" data-size="md">
    <span class="corn-pill" data-size="md">
      <span class="corn-pill-label">production</span>
      <button type="button" class="corn-pill-remove" aria-label="Remove production"></button>
    </span>
    <input class="corn-pills-input-field" role="combobox" aria-expanded="false" aria-label="Environments" />
  </div>
</div>

Classes

Vanilla JS

Required for behaviour — adds filters the options as you type, handles keyboard selection, and builds the pills and the listbox.

import { createMultiSelect } from '@corndev/ui';
import '@corndev/ui/theme';

const el = document.querySelector('#target');
const instance = createMultiSelect(el, { /* options */ });

Options

React

MultiSelect — from @corndev/ui-react.

Controlled with value + onChange, or uncontrolled with defaultValue. onChange receives the whole next array — adding, removing and clearing all look the same to the caller. The field is built from PillsInput, Pill and the shared listbox, so selected values match every other removable token in the library.

Props

MultiSelect or TagsInput?

They look almost identical and they mean different things to the data underneath, so picking the wrong one is a modelling error rather than a cosmetic one.

Choose a multi-select for a closed set — the security schemes a document declares, the roles a system defines. Choose a tags input for an open one — a document’s tags, an enum’s values, OAuth scopes.

Selected values stay in the list

A chosen option is not removed from the dropdown. It stays where it was, marked with a check, for two reasons: the list does not shuffle under the cursor as you pick, and a second click un-picks the thing you just picked — which is what a list of checkboxes does.

<MultiSelect
  options={['production', 'staging', 'development']}
  defaultValue={['production']}
  aria-label="Environments"
/>

Labels separate from values

Pass objects when what the user reads is not what you store. The pill shows the label; onChange gives you the values.

<MultiSelect
  options={[
    { label: 'API key', value: 'apiKey' },
    { label: 'OAuth 2', value: 'oauth2' },
  ]}
  defaultValue={['oauth2']}
  aria-label="Schemes"
/>

The keyboard

Backspace only acts on an empty field, so it never eats a value while you are still typing over it.

Every pill’s remove button is a real <button> named for the value it removes — “Remove production”, not “Remove” — so a keyboard or screen-reader user can tell six of them apart.

Inside a Field

id, name, aria-label and the rest go to the input, not the wrapper, so a Field around this wires its label and description to the thing a screen reader lands on. className stays on the wrapper, which is what positions the dropdown.

<Field label="Environments" description="Where this deploys.">
  <MultiSelect options={['production', 'staging']} defaultValue={['staging']} />
</Field>

The interactive example at the top of this page is wrapped in a Field; the static previews below are not, so they carry their own aria-label.

Capping the count

max stops the list accepting more. The remaining options are disabled rather than hidden, so the list does not appear to have lost entries — and anything already chosen can still be removed.

Clearing the field

clearable shows a control that empties the field, and only when there is something to empty. It calls onChange with an empty array.

<MultiSelect
  options={['production', 'staging']}
  defaultValue={['production']}
  clearable
/>

Escape clears too, while the field has focus and the list is shut. When the list is open Escape closes it instead — that is what Escape means when something is in the way.

The control is deliberately not in the tab order. A field that tabs to its input, then its clear control, then its list is tedious to escape, and the keyboard already has Escape. The control is for the pointer.

Its accessible name says what it clears rather than just “Clear”, because a form with several of these otherwise announces the same button three times. Its pointer target is 24px even though the glyph is 1rem — the shared target rule does that.