Components · Controls

Multi select

A searchable dropdown of a field’s values, any number of which can be chosen.

Open in playground

Preview

Plan

Usage

tsx
import { useState } from 'react';
import { ChartsProvider, MultiSelect, dimension, results } from 'em-kit';

const plan = dimension({ name: 'plan', title: 'Plan' });

export const Example = () => {
  const [selected, setSelected] = useState<string[]>([]);
  return (
    <ChartsProvider>
      <div style={{ width: 320 }}>
        <MultiSelect
          title="Plan"
          dimension={plan}
          results={results(options)}
          selectedValues={selected}
          onChange={setSelected}
        />
      </div>
    </ChartsProvider>
  );
};

const options = [
  { plan: 'Starter' },
  { plan: 'Growth' },
  { plan: 'Enterprise' },
];
  • results holds one row per option. The choice is reported when the reader presses Apply.

Install with npm install em-kit. Needs <ChartsProvider> once, and your own state for its value: Quick start.

Examples

Select all

A “select all” row, and each tick applied as it is made. “Select all” shows only when every value is loaded: fewer rows than the 200-option limit.

tsxDiffers from Usage
Show full code (29 lines)
import { useState } from 'react';
import { ChartsProvider, MultiSelect, dimension, results } from 'em-kit';

const plan = dimension({ name: 'plan', title: 'Plan' });

export const Example = () => {
  const [selected, setSelected] = useState<string[]>([]);
  return (
    <ChartsProvider>
      <div style={{ width: 320 }}>
        <MultiSelect
          title="Plan"
          dimension={plan}
          results={results(options)}
          selectedValues={selected}
          onChange={setSelected}
          showSelectAll
          autoApply
        />
      </div>
    </ChartsProvider>
  );
};

const options = [
  { plan: 'Starter' },
  { plan: 'Growth' },
  { plan: 'Enterprise' },
];
const plan = dimension({ name: 'plan', title: 'Plan' });

<MultiSelect
  title="Plan"
  dimension={plan}
  results={results(options)}
  selectedValues={selected}
  onChange={setSelected}
  showSelectAll
  autoApply
/>

Props

Keyboard and screen readers: Accessibility.

PropTypeDefaultDescription
dimensionrequiredDimensionThe field whose values are the options. Its formatting and translations label them.
resultsrequiredDataResponseOne row per option, holding the dimension value. results(rows) builds it from an array.
optionalSecondDimensionDimensionA second field in the same rows. When set, its values are what is chosen and reported, while dimension labels the options: show a name, report an id.
placeholderstring"Select values..."Text shown while nothing is chosen. Translates like title.
selectedValuesstring[]The chosen values.
maxOptionsnumber200The most options your query loads. “Select all” is offered only when results holds fewer rows than this: a full page may not be every value.
showSelectAllbooleanfalseOffer “select all” and “deselect all”, when results holds fewer rows than maxOptions.
autoApplybooleanfalseReport each tick as it is made, with no Apply button.
clearablebooleantrueLet the reader clear the choice. When false and nothing is chosen, the first option is selected.
componentNamestringA name for this component, included in the interaction events it dispatches on the DOM, for your analytics.
trackingIdstringAn id included in the same events, to tell two instances apart.
setSearchValue(search: string) => voidCalled with what the reader types in the search box, after a pause, so that you can query the matching options. When unset, the options are filtered by label as the reader types.
onChange(newValues: string[]) => voidCalled with the chosen values when the reader presses Apply, or at each tick with autoApply.
titlestringThe title over the field. A "key|fallback" string is looked up in your translations.
descriptionstringSmaller text under the title. Translates like title.
tooltipstringText for an info icon beside the title.

A blank default means the prop is unset unless you pass it.

Field options

MultiSelect reads only the common options in a field’s inputs.