Multi select
A searchable dropdown of a field’s values, any number of which can be chosen.
Preview
Plan
Usage
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' },
];resultsholds 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.
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.
| Prop | Type | Default | Description |
|---|---|---|---|
dimensionrequired | Dimension | The field whose values are the options. Its formatting and translations label them. | |
resultsrequired | DataResponse | One row per option, holding the dimension value. results(rows) builds it from an array. | |
optionalSecondDimension | Dimension | A 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. | |
placeholder | string | "Select values..." | Text shown while nothing is chosen. Translates like title. |
selectedValues | string[] | The chosen values. | |
maxOptions | number | 200 | The 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. |
showSelectAll | boolean | false | Offer “select all” and “deselect all”, when results holds fewer rows than maxOptions. |
autoApply | boolean | false | Report each tick as it is made, with no Apply button. |
clearable | boolean | true | Let the reader clear the choice. When false and nothing is chosen, the first option is selected. |
componentName | string | A name for this component, included in the interaction events it dispatches on the DOM, for your analytics. | |
trackingId | string | An id included in the same events, to tell two instances apart. | |
setSearchValue | ( | Called 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 | ( | Called with the chosen values when the reader presses Apply, or at each tick with autoApply. | |
title | string | The title over the field. A "key|fallback" string is looked up in your translations. | |
description | string | Smaller text under the title. Translates like title. | |
tooltip | string | Text 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.