Combobox

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

Demo

React

Vue

React

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

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

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

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

Vue

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

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

const {
  collection,
  filter,
} = useListCollection<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 },
  ],
  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>

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
onChange	(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

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'