ListBox

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

Demo

React

Vue

Usage

React

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

const collection = createListCollection<ListCollectionItem>({
  items: [
    { label: 'Dog', value: 'dog', group: 'Mammals' },
    { label: 'Cat', value: 'cat', group: 'Mammals' },
    { label: 'Canary', value: 'canary', group: 'Birds' },
    { label: 'Parrot', value: 'parrot', group: 'Birds' },
    { label: 'Goldfish', value: 'goldfish', group: 'Aquatic' },
    { label: 'Turtle', value: 'turtle', group: 'Aquatic', disabled: true },
  ],
  groupBy: item => item.group ?? '',
});

return (
  <ListBox
    collection={collection}
    label="Choose a pet"
  />
);

Vue

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

const collection = createListCollection<ListCollectionItem>({
  items: [
    { label: 'Dog', value: 'dog', group: 'Mammals' },
    { label: 'Cat', value: 'cat', group: 'Mammals' },
    { label: 'Canary', value: 'canary', group: 'Birds' },
    { label: 'Parrot', value: 'parrot', group: 'Birds' },
    { label: 'Goldfish', value: 'goldfish', group: 'Aquatic' },
    { label: 'Turtle', value: 'turtle', group: 'Aquatic', disabled: true },
  ],
  groupBy: item => item.group ?? '',
});
</script>

<template>
  <ListBox
    :collection="collection"
    label="Choose a pet"
  />
</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
onChange	(value: string[]) => void	Callback fired when the value changes
onSelect	(value: string) => void	Callback fired when an item is selected

Vue

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

Types

type Collection = ListCollection<ListCollectionItem>

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

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