ListBox

The ListBox component is used to display data.

Basic usage

const options = [
  {
    id: "michael",
    name: "Michael Murphy",
    birthDate: "19/09/1979",
    avatar: "/aurelien.webp",
    description: "Growth team",
  },
  // other options
];

const Demo = () => {
  const [activeOption, setActiveOption] = useState<string | undefined>();

  return (
    <ListBox
      getOptionId={(option) => option.id}
      options={options}
      getIsOptionActive={(option) => option.id === activeOption}
      onOptionClick={(option) => {
        setActiveOption(option.id);
      }}
      aria-label="Employees"
    >
      {(option, titleId) => (
        <div className="flex gap-16 items-center">
          <Avatar variant="circle" src={option.avatar} text={option.name} />
          <div className="flex-grow">
            <div className="title-m" id={titleId}>
              {option.name}
            </div>
            <div className="body-m text-secondary-bg-primary mt-4">
              {option.description}
            </div>
          </div>
          <span>{option.birthDate}</span>
        </div>
      )}
    </ListBox>
  );
};

Empty state

If no data has been provided, the list's empty state will appear. The title is mandatory, and the subtitle is optional.

<ListBox
  options={[]}
  emptyState={{
    title: "No employee found",
    subtitle: "Add employees to get started",
  }}
  {...otherProps}
/>

Row height

The ListBox component has two variants: normal and compact. The compact mode makes the rows smaller.

<ListBox rowHeight="compact" {...otherProps} />

The header and footer props allow you to specify a header or a footer for the ListBox component.

<ListBox
  header={<div>Members</div>}
  footer={
    <div className="my-8 mx-auto">
      <Button fit="content" text="Load more" variant="secondaryNeutral" />
    </div>
  }
  {...otherProps}
/>

Disabled rows

The getIsOptionDisabled prop allows you to disable options in the ListBox. These options will be neither clickable nor selectable.

<ListBox
  getIsOptionDisabled={(option) => option.id === "laura"}
  {...otherProps}
/>

Groups

ListBox options can be grouped, with the groupBy and renderGroupedOptionsHeader props.

<ListBox
  groupBy={(option) => {
    const date = new Date(option.birthDate);
    return `${date.getFullYear()}`;
  }}
  renderGroupedOptionsHeader={(value, aggregatedOptions) => {
    const aggregatedCount = aggregatedOptions.length;
    return (
      <div className="flex justify-between">
        <span>{value}</span>
        <span>
          {aggregatedCount} {aggregatedCount > 1 ? "members" : "member"}
        </span>
      </div>
    );
  }}
  {...otherProps}
/>

If you want to make a ListBox component selectable, you will need to specify the following props: onOptionChange, onAllOptionsChange, and checkedOptionIds. Options that have been disabled with getIsOptionDisabled are not selectable. You can also specify directly if an option should be selectable with getIsOptionCheckable, without having to disable the row.

const [optionsSelected, setOptionSelected] = useState<string[]>([]);

return (
  <ListBox
    onOptionChange={(_, id, checked) => {
      setOptionSelected((options) => {
        if (checked) {
          return options.concat(id);
        }
        return options.filter((optionId) => optionId !== id);
      });
    }}
    onAllOptionsChange={(_, ids, checked) => {
      setOptionSelected(checked ? ids : []);
    }}
    checkedOptionIds={optionsSelected}
    {...otherProps}
  />
);

Option variant

The getOptionVariant prop allows you to specify a variant (alert or warning) for the different options.

<ListBox
  getOptionVariant={(option) => {
    switch (option.id) {
      case "george":
        return "alert";
      case "lewis":
        return "warning";
      default:
        return undefined;
    }
  }}
  {...otherProps}
/>