Checkbox multi select

Checkbox Multi Select is a multi-select dropdown that shows a checkbox next to each option. Use it when users need to toggle several values, such as columns, tags, or filters. The trigger shows selectLabel when anything is selected, rather than chips of every value.

Example

Columns

Props

Prop	Type	Default value	Description
Prop value	Type string[]	Default value undefined	Description Currently selected values (controlled). Prefer this with onSelect.
Prop defaultValue	Type string[]	Default value []	Description Initial selected values when the component is uncontrolled
Prop onSelect	Type (value: string[], type?: "custom" \| "default") => void	Default value undefined	Description Called with the full array of selected values whenever the selection changes
Prop options	Type Array<{ value: string; label: ReactNode; description?: ReactNode; disabled?: boolean; icon?: IconName }>	Default value undefined	Description Option list. Mutually exclusive with children. Groups use { heading, options }.
Prop children	Type ReactNode	Default value undefined	Description Option list as CheckboxMultiSelect.Group / Item / ItemDescription. Mutually exclusive with options.
Prop label	Type ReactNode	Default value undefined	Description Label displayed above the field
Prop placeholder	Type string	Default value "Select an option"	Description Trigger text when nothing is selected
Prop selectLabel	Type string	Default value undefined	Description Trigger text when at least one option is selected. Without it, the first selected option label is shown.
Prop disabled	Type boolean	Default value false	Description Whether the field is disabled and cannot be opened
Prop error	Type ReactNode	Default value undefined	Description Error message or truthy value that puts the field in an error state
Prop showSearch	Type boolean	Default value false	Description Whether to show a search field at the top of the dropdown
Prop useFullWidthItems	Type boolean	Default value false	Description Whether option rows stretch to the full width of the dropdown
Prop itemCharacterLimit	Type string	Default value "64ch"	Description Maximum width of option labels before they truncate
Prop maxHeight	Type string	Default value undefined	Description Maximum height of the dropdown menu (for example "300px" or "50vh")
Prop allowCreateOption	Type boolean	Default value false	Description Whether users can create a new option from the current search text
Prop noAvailableOptions	Type boolean \| function	Default value true	Description What to render when nothing matches. true shows the default empty message. A function receives { search, close }.
Prop defaultOpen	Type boolean	Default value false	Description Whether the dropdown is open on first render
Prop onOpenChange	Type (open: boolean) => void	Default value undefined	Description Called when the dropdown opens or closes

Item props

Use CheckboxMultiSelect.Item when you pass options as children.

Prop	Type	Default value	Description
Prop value	Type string	Default value ""	Description Value stored in the selected array when this item is checked
Prop label	Type ReactNode	Default value undefined	Description Option label. Use this or children, not both.
Prop description	Type ReactNode	Default value undefined	Description Secondary text under the label. Also available as CheckboxMultiSelect.ItemDescription.
Prop disabled	Type boolean	Default value false	Description Whether this option cannot be selected
Prop icon	Type IconName	Default value undefined	Description Optional icon shown with the option
Prop iconDir	Type "start" \| "end"	Default value "end"	Description Which side of the label to place the icon
Prop variant	Type "default" \| "var1" \| "var2" \| "var3" \| "var4" \| "var5" \| "var6" \| "var7"	Default value "default"	Description Checkbox color variant for this option
Prop separator	Type boolean	Default value false	Description Whether to render a separator after this item

Group props

Prop	Type	Default value	Description
Prop heading	Type ReactNode	Default value undefined	Description Group heading shown above the items in this group

Quick start

onSelect receives the full selected array, not a single value:

import { CheckboxMultiSelect } from '@clickhouse/click-ui'
import { useState } from 'react'

function ColumnPicker() {
const [values, setValues] = useState<string[]>([])

return (
  <CheckboxMultiSelect
    label="Columns"
    placeholder="Select columns"
    selectLabel="Columns"
    value={values}
    onSelect={setValues}
    options={[
      { label: 'Name', value: 'name' },
      { label: 'Status', value: 'status' },
      { label: 'Created at', value: 'createdAt' },
    ]}
  />
)
}

Select: For choosing a single option, or chips-style multi-select with isMulti.
Checkbox: For standalone checkboxes outside a dropdown.
Label: Provides accessible labels for form fields.
Container: For laying out the picker with other form fields.

Common use cases

Options as children

Use Group, Item, and ItemDescription when options need icons, descriptions, or mixed layout.

Sources

import { CheckboxMultiSelect } from '@clickhouse/click-ui'
import { useState } from 'react'

function SourcesPicker() {
const [values, setValues] = useState<string[]>(['logs'])

return (
  <CheckboxMultiSelect
    label="Sources"
    placeholder="Select sources"
    selectLabel="Sources"
    value={values}
    onSelect={setValues}
  >
    <CheckboxMultiSelect.Group heading="ClickHouse">
      <CheckboxMultiSelect.Item value="query" icon="table" iconDir="start">
        Query log
      </CheckboxMultiSelect.Item>
      <CheckboxMultiSelect.Item value="metrics" icon="metrics" iconDir="start">
        Metrics
      </CheckboxMultiSelect.Item>
    </CheckboxMultiSelect.Group>
    <CheckboxMultiSelect.Item value="logs">
      Application logs
      <CheckboxMultiSelect.ItemDescription>
        Includes stdout and error streams
      </CheckboxMultiSelect.ItemDescription>
    </CheckboxMultiSelect.Item>
    <CheckboxMultiSelect.Item value="traces" disabled label="Traces" />
  </CheckboxMultiSelect>
)
}

With search

Regions

import { CheckboxMultiSelect } from '@clickhouse/click-ui'
import { useState } from 'react'

function RegionPicker() {
const [values, setValues] = useState<string[]>([])

return (
  <CheckboxMultiSelect
    label="Regions"
    placeholder="Select regions"
    selectLabel="Regions"
    showSearch
    value={values}
    onSelect={setValues}
    options={[
      { label: 'us-east-1', value: 'us-east-1' },
      { label: 'eu-west-1', value: 'eu-west-1' },
    ]}
  />
)
}

Checkbox variants

Each item can use the same variant values as Checkbox.

import { CheckboxMultiSelect } from '@clickhouse/click-ui'
import { useState } from 'react'

function VariantPicker() {
const [values, setValues] = useState<string[]>(['var1'])

return (
  <CheckboxMultiSelect
    placeholder="Select variants"
    selectLabel="Selected"
    value={values}
    onSelect={setValues}
  >
    <CheckboxMultiSelect.Item value="var1" variant="var1">
      Variant 1
    </CheckboxMultiSelect.Item>
    <CheckboxMultiSelect.Item value="var2" variant="var2">
      Variant 2
    </CheckboxMultiSelect.Item>
  </CheckboxMultiSelect>
)
}

Error and disabled

Select at least one column

Required columns

Disabled

import { CheckboxMultiSelect, Container } from '@clickhouse/click-ui'

<Container orientation="vertical" gap="md">
<CheckboxMultiSelect
  label="Required columns"
  placeholder="Select columns"
  error="Select at least one column"
  options={options}
/>
<CheckboxMultiSelect
  label="Disabled"
  placeholder="Select columns"
  disabled
  options={options}
/>
</Container>

Select Autocomplete