Components · Controls

Single select

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

Open in playground

Preview

Region

Usage

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

const region = dimension({ name: 'region', title: 'Region' });

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

const options = [
  { region: 'North America' },
  { region: 'Europe' },
  { region: 'Asia Pacific' },
  { region: 'Latin America' },
  { region: 'Middle East' },
];
  • results holds one row per option. Labels are formatted like the field anywhere else, so translated values match the charts.

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

Examples

Always a value

Not clearable: with nothing chosen, the first option is selected.

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

const region = dimension({ name: 'region', title: 'Region' });

export const Example = () => {
  const [selected, setSelected] = useState<string>();
  return (
    <ChartsProvider>
      <div style={{ width: 320 }}>
        <SingleSelect
          title="Region"
          dimension={region}
          results={results(options)}
          selectedValue={selected}
          onChange={setSelected}
          clearable={false}
        />
      </div>
    </ChartsProvider>
  );
};

const options = [
  { region: 'North America' },
  { region: 'Europe' },
  { region: 'Asia Pacific' },
  { region: 'Latin America' },
  { region: 'Middle East' },
];
const region = dimension({ name: 'region', title: 'Region' });

<SingleSelect
  title="Region"
  dimension={region}
  results={results(options)}
  selectedValue={selected}
  onChange={setSelected}
  clearable={false}
/>

Props

Not listed: maxOptions, which the type accepts and the component does not read. 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 value is what is chosen and reported, while dimension labels the option: show a name, report an id.
placeholderstring"Select value..."Text shown while nothing is chosen. Translates like title.
selectedValuestringThe chosen value.
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(selectedValue: string) => voidCalled with the value the reader picks, or with undefined when the reader clears it.
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

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