ListBox

A component for selecting a single or multiple items from a list.

Demo

React

Vue

Usage

React

import {
  createListCollection,
  ListBox,
} from '@fintech-sandpit/ui/react';

const collection = createListCollection({
  items: [
    { label: 'Dog', value: 'dog', description: 'A dog is known for its loyalty and companionship.', group: 'Mammals' },
    { label: 'Cat', value: 'cat', description: 'A cat is known for its independence and curiosity.', group: 'Mammals' },
    { label: 'Canary', value: 'canary', description: 'A canary is known for its song.', group: 'Birds' },
    { label: 'Parrot', value: 'parrot', description: 'A parrot is known for its intelligence and ability to mimic human speech.', group: 'Birds' },
    { label: 'Goldfish', value: 'goldfish', description: 'A goldfish is known for its beauty and rarity.', group: 'Aquatic' },
    { label: 'Turtle', value: 'turtle', description: 'A turtle is known for its longevity and wisdom.', group: 'Aquatic', disabled: true },
  ],
  groupBy: item => item.group ?? '',
});

return (
  <ListBox
    collection={collection}
    label="Choose a pet"
    ItemText={({ item }) => (
      <div className="flex flex-col gap-1">
        <span>
          {item.label}
        </span>

        <span className="text-sm text-gray-400 dark:text-gray-600">
          {item.description}
        </span>
      </div>
    )}
  />
);

Vue

<script setup lang="ts">
import {
  createListCollection,
  ListBox,
} from '@fintech-sandpit/ui/vue';

const collection = createListCollection({
  items: [
    { label: 'Dog', value: 'dog', description: 'A dog is known for its loyalty and companionship.', group: 'Mammals' },
    { label: 'Cat', value: 'cat', description: 'A cat is known for its independence and curiosity.', group: 'Mammals' },
    { label: 'Canary', value: 'canary', description: 'A canary is known for its song.', group: 'Birds' },
    { label: 'Parrot', value: 'parrot', description: 'A parrot is known for its intelligence and ability to mimic human speech.', group: 'Birds' },
    { label: 'Goldfish', value: 'goldfish', description: 'A goldfish is known for its beauty and rarity.', group: 'Aquatic' },
    { label: 'Turtle', value: 'turtle', description: 'A turtle is known for its longevity and wisdom.', group: 'Aquatic', disabled: true },
  ],
  groupBy: item => item.group ?? '',
});
</script>

<template>
  <ListBox
    :collection="collection"
    label="Choose a pet"
    ItemText={({ item }) => (
      <div className="flex flex-col gap-1">
        <span>
          {{ item.label }}
        </span>
      </div>

        <span className="text-sm text-gray-400 dark:text-gray-600">
          {{ item.description }}
        </span>
      </div>
    )}
  />
</template>

Props

React

Name	Type	Default	Description
value	string[]	—	The value of the list box
defaultValue	string[]	—	The default value of the list box
collection	Collection	—	The collection of the list box
label	string	—	The label of the list box
size	Size	md	The size of the list box
required	boolean	false	Whether the list box is required
multiple	boolean	false	Whether the list box selection can contain multiple items
invalid	boolean	false	Whether the list box is invalid
disabled	boolean	false	Whether the list box is disabled

Vue

Name	Type	Default	Description
model-value	string[]	—	The value of the list box 1
default-value	string[]	—	The default value of the list box
collection	Collection	—	The collection of the list box
label	string	—	The label of the list box
size	Size	md	The size of the list box
required	boolean	false	Whether the list box is required
multiple	boolean	false	Whether the list box selection can contain multiple items
invalid	boolean	false	Whether the list box is invalid
disabled	boolean	false	Whether the list box is disabled

1. Can be used with the v-model directive for two-way binding.

Events

React

Name	Type	Description
onSelect	(value: string) => void	Callback fired when an item is selected
onValueChange	(value: string[]) => void	Callback fired when the value changes

Vue

Name	Payload	Description
select	string	Event emitted when an item is selected
update:model-value	string[]	Event emitted when the value changes

Slots

React

Prop name	Props	Description
ItemText	{ item: ListCollectionItem; }	Component for the custom item text

Vue

Slot name	Props	Description
item-text	{ item: ListCollectionItem; }	Slot for the custom item text

Types

type Collection = ListCollection<ListCollectionItem>

type ListCollectionItem = {
  label: string;
  value: string;
  disabled?: boolean;
  group?: string;
}

type Size = 'xs' | 'sm' | 'md' | 'lg' | 'xl'