Combobox

A single input field that combines the functionality of a select and input.

Demo

React

Vue

React

import {
  Combobox,
  useFilter,
  useListCollection,
} from '@fintech-sandpit/ui/react';

const filters = useFilter({
  sensitivity: 'base',
});

const {
  collection,
  filter,
} = useListCollection({
  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 },
  ],
  filter: filters.contains,
  groupBy: item => item.group ?? '',
});

return (
  <Combobox
    collection={collection}
    placeholder="Select a pet, e.g. cat"
    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>
    )}
    onInputValueChange={({ inputValue }) => filter(inputValue)}
  />
);

Vue

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

const filters = useFilter({
  sensitivity: 'base',
});

const {
  collection,
  filter,
} = useListCollection({
  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 },
  ],
  filter: filters.value.contains,
  groupBy: item => item.group ?? '',
});
</script>

<template>
  <Combobox
    :collection="collection"
    placeholder="Select a pet, e.g. cat"
    @input-value-change="({ inputValue }) => filter(inputValue)"
  >
    <template #item-text="{ item }">
      <div class="flex flex-col gap-1">
        <span>
          {{ item.label }}
        </span>
      </div>

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

Props

React

Name	Type	Default	Description
value	string[]	—	Controlled value of the combobox
defaultValue	string[]	—	Default (uncontrolled) value of the combobox
collection	Collection	—	Options of the combobox
size	Size	md	Size of the combobox
multiple	boolean	false	Whether the combobox is multiple
clearable	boolean	false	Whether the combobox is clearable (a ‘x’ icon is shown)
invalid	boolean	false	Whether the combobox is invalid
readOnly	boolean	false	Whether the combobox is read only
disabled	boolean	false	Whether the combobox is disabled
placeholder	string	—	Placeholder of the combobox

Vue

Name	Type	Default	Description
model-value	string[]	—	Controlled value of the combobox 1
default-value	string[]	—	Default (uncontrolled) value of the combobox
collection	Collection	—	Options of the combobox
size	Size	md	Size of the combobox
multiple	boolean	false	Whether the combobox is multiple
clearable	boolean	false	Whether the combobox is clearable (a ‘x’ icon is shown)
invalid	boolean	false	Whether the combobox is invalid
read-only	boolean	false	Whether the combobox is read only
disabled	boolean	false	Whether the combobox is disabled
placeholder	string	—	Placeholder of the combobox

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

Events

React

Name	Type	Description
onValueChange	(value: string[]) => void	Callback fired when the value changes
onInputValueChange	(details: ChangeDetails) => void	Callback fired when the combobox input value changes

Vue

Name	Payload	Description
update:model-value	string[]	Event emitted when the value changes
input-value-change	ChangeDetails	Event emitted when the combobox input 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 ChangeDetails = {
  inputValue: string;
  reason?: 'input-change' | 'item-select' | 'clear-trigger' | 'script' | 'interact-outside';
}

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