Combobox

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

Demo

React

Vue

Example

React

import { useState } from '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: 'Loyal companion', group: 'Mammals' },
    { label: 'Cat', value: 'cat', description: 'Independent and curious', group: 'Mammals' },
    { label: 'Canary', value: 'canary', description: 'Known for its song', group: 'Birds' },
    { label: 'Parrot', value: 'parrot', description: 'Can mimic speech', group: 'Birds' },
    { label: 'Goldfish', value: 'goldfish', description: 'Beautiful and rare', group: 'Aquatic' },
    { label: 'Turtle', value: 'turtle', description: 'Longevity and wisdom', group: 'Aquatic', disabled: true },
  ],
  filter: filters.contains,
  groupBy: item => item.group ?? '',
});

const [value, setValue] = useState<string[]>(['dog']);

return (
  <Combobox
    value={value}
    defaultValue={['cat']}
    collection={collection}
    size="md"
    multiple
    clearable
    invalid={false}
    readOnly={false}
    disabled={false}
    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-500">{item.description}</span>
      </div>
    )}
    onInputValueChange={({ inputValue }) => filter(inputValue)}
    onValueChange={({ value }) => setValue(value)}
  />
);

Vue

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

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

const { collection, filter } = useListCollection({
  items: [
    { label: 'Dog', value: 'dog', description: 'Loyal companion', group: 'Mammals' },
    { label: 'Cat', value: 'cat', description: 'Independent and curious', group: 'Mammals' },
    { label: 'Canary', value: 'canary', description: 'Known for its song', group: 'Birds' },
    { label: 'Parrot', value: 'parrot', description: 'Can mimic speech', group: 'Birds' },
    { label: 'Goldfish', value: 'goldfish', description: 'Beautiful and rare', group: 'Aquatic' },
    { label: 'Turtle', value: 'turtle', description: 'Longevity and wisdom', group: 'Aquatic', disabled: true },
  ],
  filter: filters.contains,
  groupBy: item => item.group ?? '',
});

const value = ref<string[]>(['dog']);
</script>

<template>
  <Combobox
    v-model="value"
    :default-value="['cat']"
    :collection="collection"
    size="md"
    multiple
    clearable
    :invalid="false"
    :read-only="false"
    :disabled="false"
    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>

        <span className="text-sm text-gray-500">{{ 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'