Framework
1.13.0 GitHub️ 2.6k

Select input

API · Source · The select input allows the user to choose from a given set of values. A select is recommended over a radio or checkbox input when the number of values to choose from is large — say, eight or more — to save space.

The default appearance of a select is a drop-down menu that allows you to choose a single value. The initial value is the first of the allowed values, but you can override this by specifying the value option.

const color = view(Inputs.select(x11colors, {value: "steelblue", label: "Favorite color"}));

color

If the multiple option is true, the select will allow multiple values to be selected and the value of the select will be the array of selected values. The initial value is the empty array. You can choose a range of values by dragging or Shift-clicking, and select or deselect a value by Command-clicking.

const colors = view(Inputs.select(x11colors, {multiple: true, label: "Favorite colors"}));

colors

The multiple option can also be a number indicating the desired size: the number of rows to show. If multiple is true, the size defaults to the number of allowed values, or ten, whichever is fewer.

const fewerColors = view(Inputs.select(x11colors, {multiple: 4, label: "Favorite colors"}));

fewerColors

For single-choice selects, if you wish to allow no choice to be selected, we recommend including null as an explicit option.

const maybeColor = view(Inputs.select([null].concat(x11colors), {label: "Favorite color"}));

maybeColor

A select’s values need not be strings: they can be anything. Specify a format function to control how these values are presented to the reader.

const teams = [
  {name: "Lakers", location: "Los Angeles, California"},
  {name: "Warriors", location: "San Francisco, California"},
  {name: "Celtics", location: "Boston, Massachusetts"},
  {name: "Nets", location: "New York City, New York"},
  {name: "Raptors", location: "Toronto, Ontario"},
];

const favorite = view(
  Inputs.select(teams, {
    label: "Favorite team",
    format: (t) => t.name,
    value: teams.find((t) => t.name === "Warriors")
  })
);

favorite

If the select’s data are specified as a Map, the values will be the map’s values while the keys will be the displayed options. (This behavior can be customized by passing keyof and valueof function options.) Below, the displayed sizes are named, but the value is the corresponding number of fluid ounces.

const size = view(
  Inputs.select(
    new Map([
      ["Short", 8],
      ["Tall", 12],
      ["Grande", 16],
      ["Venti", 20]
    ]),
    {value: 12, label: "Size"}
  )
);

size

Since the format function is passed elements from the data, it can access both the key and value from the corresponding Map entry.

const size2 = view(
  Inputs.select(
    new Map([
      ["Short", 8],
      ["Tall", 12],
      ["Grande", 16],
      ["Venti", 20]
    ]),
    {value: 12, label: "Size", format: ([name, value]) => `${name} (${value} oz)`}
  )
);

size2

Passing a Map to select is especially useful in conjunction with d3.group. For example, given a tabular dataset of Olympic athletes (olympians), we can use d3.group to group them by sport, and then the select input to select only athletes for the chosen sport.

const sportAthletes = view(
  Inputs.select(
    d3.group(olympians, (d) => d.sport),
    {label: "Sport"}
  )
);

sportAthletes

If the sort and unique options are specified, the select’s keys will be sorted and duplicate keys will be discarded, respectively.

const sport = view(
  Inputs.select(
    olympians.map((d) => d.sport),
    {label: "Sport", sort: true, unique: true}
  )
);

sport

The disabled option, if true, disables the entire select. If disabled is an array, then only the specified values are disabled.

Inputs.select(["A", "E", "I", "O", "U", "Y"], {label: "Vowel", disabled: true})

Inputs.select(["A", "E", "I", "O", "U", "Y"], {label: "Vowel", disabled: ["Y"]})

Options

Inputs.select(data, options)

The available select input options are: