# Multi select

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

- Component: `<MultiSelect />`, imported from `em-kit`
- Required props: `dimension` and `results`
- HTML page, with live previews: https://emkit.embeddable.com/docs/components/multi-select
- Playground (needs a browser): https://emkit.embeddable.com/docs/components/multi-select/playground

## Install

```bash
npm install em-kit
pnpm add em-kit   # or, with pnpm
yarn add em-kit   # or, with yarn
bun add em-kit   # or, with bun
```

`react` and `react-dom` 19.1.1 or later are the only peer dependencies; Chart.js installs with the package. Wrap your app, or the part with charts, in `<ChartsProvider>` once: without it every chart throws `EmKit components must be rendered inside <ChartsProvider>.` Every example on this page includes `<ChartsProvider>` so that it runs on its own: if your app already has one, delete it from the example. A control is as wide as its parent and as tall as its title and field, so it needs no height. In the Next.js App Router, every file that renders `ChartsProvider` or a chart starts with `'use client'`, and the provider pins the locale, `theme={{ formatter: { locale: 'en-US' } }}`, so the server and the browser format numbers alike. [The quick start](/docs/quick-start.md#in-the-nextjs-app-router) has the Next.js files.

## 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.

## States

The select draws its own states from `results`: a spinner while `isLoading` is true, and “No options found” when `data` is `[]` or `error` is set. Pass your query’s state straight through.

## 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.

```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}
          showSelectAll
          autoApply
        />
      </div>
    </ChartsProvider>
  );
};

const options = [
  { plan: 'Starter' },
  { plan: 'Growth' },
  { plan: 'Enterprise' },
];
```

## Props

Required props come first. A blank default means the prop is unset unless you pass it.

| Prop | Type | Required | Default | Description |
|---|---|---|---|---|
| `dimension` | `Dimension` | yes |  | The field whose values are the options. Its formatting and translations label them. |
| `results` | `DataResponse` | yes |  | One row per option, holding the `dimension` value. `results(rows)` builds it from an array. |
| `optionalSecondDimension` | `Dimension` | no |  | 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` | no | `"Select values..."` | Text shown while nothing is chosen. Translates like `title`. |
| `selectedValues` | `string[]` | no |  | The chosen values. |
| `maxOptions` | `number` | no | `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` | no | `false` | Offer “select all” and “deselect all”, when `results` holds fewer rows than `maxOptions`. |
| `autoApply` | `boolean` | no | `false` | Report each tick as it is made, with no Apply button. |
| `clearable` | `boolean` | no | `true` | Let the reader clear the choice. When `false` and nothing is chosen, the first option is selected. |
| `componentName` | `string` | no |  | A name for this component, included in the interaction events it dispatches on the DOM, for your analytics. |
| `trackingId` | `string` | no |  | An id included in the same events, to tell two instances apart. |
| `setSearchValue` | `(search: string) => void` | no |  | 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` | `(newValues: string[]) => void` | no |  | Called with the chosen values when the reader presses Apply, or at each tick with `autoApply`. |
| `title` | `string` | no |  | The title over the field. A `"key\|fallback"` string is looked up in your translations. |
| `description` | `string` | no |  | Smaller text under the title. Translates like `title`. |
| `tooltip` | `string` | no |  | Text for an info icon beside the title. |

## Field options

Options go in a field’s `inputs`, for example `measure({ name: 'revenue', inputs: { prefix: '$' } })`. Every field takes `prefix`, `suffix`, `decimalPlaces`, `currency`, `abbreviateLargeNumber`, `displayName` and `maxCharacters`. [Field options](/docs/describing-your-data.md#field-options) describes them.
