v1.6.0

Combobox

Experimental

This component is considered experimental. Reach out to the Spark team to find out more about what this means.

Open in Storybook Edit this page

Installation

Install yarn add @spark-web/combobox

npm @spark-web/combobox

Source GitHub.com

Bundle unpkg.com

The Combobox allows the user to browse, search, and make a single selection from a large list of values.

Usage

Controlled component

Who's your favourite Adventure Time character?

Select a character

Open in Playroom

const [value, setValue] = React.useState(null);

return (
  <Field label="Who's your favourite Adventure Time character?">
    <Combobox
      placeholder="Select a character"
      items={[
        { label: 'Jake', value: 'jake' },
        { label: 'Finn', value: 'finn' },
        { label: 'BMO', value: 'bmo' },
      ]}
      onChange={value => setValue(value)}
      value={value}
    />
  </Field>
);

const [value, setValue] = React.useState(null);

return (
  <Field label="Who's your favourite Adventure Time character?">
    <Combobox
      placeholder="Select a character"
      items={[
        { label: 'Jake', value: 'jake' },
        { label: 'Finn', value: 'finn' },
        { label: 'BMO', value: 'bmo' },
      ]}
      onChange={value => setValue(value)}
      value={value}
    />
  </Field>
);

Uncontrolled component

Who's your favourite Adventure Time character?

Select a character

Open in Playroom

<Field label="Who's your favourite Adventure Time character?">
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
  />
</Field>

<Field label="Who's your favourite Adventure Time character?">
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
  />
</Field>

Async

Search the interwebs

Start typing...

Open in Playroom

const [items, setItems] = React.useState([]);
const [value, setValue] = React.useState(null);

const fetchItems = async input => {
  if (!input) return [];
  await new Promise(resolve => setTimeout(resolve, 1000));
  return [{ label: input, value: input }];
};

return (
  <Field label="Search the interwebs">
    <Combobox
      placeholder="Start typing..."
      items={items}
      onChange={value => setValue(value)}
      onInputChange={input => setItems(fetchItems(input))}
      value={value}
    />
  </Field>
);

const [items, setItems] = React.useState([]);
const [value, setValue] = React.useState(null);

const fetchItems = async input => {
  if (!input) return [];
  await new Promise(resolve => setTimeout(resolve, 1000));
  return [{ label: input, value: input }];
};

return (
  <Field label="Search the interwebs">
    <Combobox
      placeholder="Start typing..."
      items={items}
      onChange={value => setValue(value)}
      onInputChange={input => setItems(fetchItems(input))}
      value={value}
    />
  </Field>
);

Custom label and value

What's your favourite movie?

Select a movie

{}

Open in Playroom

const [value, setValue] = React.useState(null);

return (
  <Field
    label="What's your favourite movie?"
    message={JSON.stringify(value ?? {})}
  >
    <Combobox
      placeholder="Select a movie"
      items={[
        { title: 'The Shawshank Redemption', year: 1994 },
        { title: 'The Godfather', year: 1972 },
        { title: 'The Godfather: Part II', year: 1974 },
        { title: 'The Dark Knight', year: 2008 },
        { title: '12 Angry Men', year: 1957 },
        { title: "Schindler's List", year: 1993 },
      ]}
      onChange={value => setValue(value)}
      value={value}
      getOptionLabel={option => option.title}
      getOptionValue={option => `${option.year}`}
    />
  </Field>
);

const [value, setValue] = React.useState(null);

return (
  <Field
    label="What's your favourite movie?"
    message={JSON.stringify(value ?? {})}
  >
    <Combobox
      placeholder="Select a movie"
      items={[
        { title: 'The Shawshank Redemption', year: 1994 },
        { title: 'The Godfather', year: 1972 },
        { title: 'The Godfather: Part II', year: 1974 },
        { title: 'The Dark Knight', year: 2008 },
        { title: '12 Angry Men', year: 1957 },
        { title: "Schindler's List", year: 1993 },
      ]}
      onChange={value => setValue(value)}
      value={value}
      getOptionLabel={option => option.title}
      getOptionValue={option => `${option.year}`}
    />
  </Field>
);

Grouped

Who's your favourite character?

Select a character

Open in Playroom

<Field label="Who's your favourite character?">
  <Combobox
    placeholder="Select a character"
    items={[
      {
        label: 'Futurama',
        options: [
          { label: 'Fry', value: 'fry' },
          { label: 'Leela', value: 'leela' },
          { label: 'Bender', value: 'bender' },
          { label: 'Zoidberg', value: 'zoidberg' },
        ],
      },
      {
        label: 'South Park',
        options: [
          { label: 'Stan', value: 'stan' },
          { label: 'Kyle', value: 'kyle' },
          { label: 'Cartman', value: 'cartman' },
          { label: 'Kenny', value: 'kenny' },
        ],
      },
    ]}
  />
</Field>

<Field label="Who's your favourite character?">
  <Combobox
    placeholder="Select a character"
    items={[
      {
        label: 'Futurama',
        options: [
          { label: 'Fry', value: 'fry' },
          { label: 'Leela', value: 'leela' },
          { label: 'Bender', value: 'bender' },
          { label: 'Zoidberg', value: 'zoidberg' },
        ],
      },
      {
        label: 'South Park',
        options: [
          { label: 'Stan', value: 'stan' },
          { label: 'Kyle', value: 'kyle' },
          { label: 'Cartman', value: 'cartman' },
          { label: 'Kenny', value: 'kenny' },
        ],
      },
    ]}
  />
</Field>

With Default Option

Who's your favourite Adventure Time character?

Select a character

Open in Playroom

<Field label="Who's your favourite Adventure Time character?">
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
    defaultOption={{
      option: { label: 'The Ice King', value: 'ice king' },
      position: 'start',
    }}
  />
</Field>

<Field label="Who's your favourite Adventure Time character?">
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
    defaultOption={{
      option: { label: 'The Ice King', value: 'ice king' },
      position: 'start',
    }}
  />
</Field>

Appearance

Disabled

Who's your favourite Adventure Time character?

Select a character

Open in Playroom

<Field label="Who's your favourite Adventure Time character?" disabled>
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
  />
</Field>

<Field label="Who's your favourite Adventure Time character?" disabled>
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
  />
</Field>

Invalid

Who's your favourite Adventure Time character?

Select a character

Required

Open in Playroom

<Field
  label="Who's your favourite Adventure Time character?"
  tone="critical"
  message="Required"
>
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
  />
</Field>

<Field
  label="Who's your favourite Adventure Time character?"
  tone="critical"
  message="Required"
>
  <Combobox
    placeholder="Select a character"
    items={[
      { label: 'Jake', value: 'jake' },
      { label: 'Finn', value: 'finn' },
      { label: 'BMO', value: 'bmo' },
    ]}
  />
</Field>

Props

Prop	Type	Description
items	Awaitable<(Item \| GroupBase<Item>)[]>	Array of items for the user to select from.
data?	DataAttributeMap	Sets data attributes on the component.
defaultOption?	DefaultOption<Item>	Option that will be displayed regardless of filter results
getOptionLabel?	GetOptionLabel<Item>	Resolves option data to a string to be displayed as the label by components. Note: Failure to resolve to a string type can interfere with filtering and screen reader support.
getOptionValue?	GetOptionValue<Item>	Resolves option data to a string to compare options and specify value attributes.
inputValue?	string	The value of the input.
isLoading?	boolean	When true, shows a loading indicator in the dropdown instead of results.
menuPortalTarget?	HTMLElement	Whether the menu should use a portal, and where it should attach.
onChange?	(value: Item) => void	Called when an item is selected.
onInputChange?	(inputValue: string) => void	Called whenever the input value changes. Use to filter the items.
placeholder?	string	The text that appears in the form control when it has no value set.
value?	Item	The selected item.