--- title: Checkbox multi select description: Checkbox Multi Select lets users pick multiple options from a dropdown where each option is a checkbox. category: Forms related: [Select, Checkbox, Label, Container] commonPatterns: [column-picker, filter-multi-select, grouped-checkbox-select] --- Source: https://clickhouse.design/click-ui/checkboxmultiselect # 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 ## Props | Prop | Type | Default value | Description | | ------------------ | ---------------------------------------------------------------------------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ | | value | `string[]` | `undefined` | Currently selected values (controlled). Prefer this with onSelect. | | defaultValue | `string[]` | `[]` | Initial selected values when the component is uncontrolled | | onSelect | `(value: string[], type?: "custom" \| "default") => void` | `undefined` | Called with the full array of selected values whenever the selection changes | | options | `Array<{ value: string; label: ReactNode; description?: ReactNode; disabled?: boolean; icon?: IconName }>` | `undefined` | Option list. Mutually exclusive with children. Groups use \{ heading, options }. | | children | `ReactNode` | `undefined` | Option list as CheckboxMultiSelect.Group / Item / ItemDescription. Mutually exclusive with options. | | label | `ReactNode` | `undefined` | Label displayed above the field | | placeholder | `string` | `"Select an option"` | Trigger text when nothing is selected | | selectLabel | `string` | `undefined` | Trigger text when at least one option is selected. Without it, the first selected option label is shown. | | disabled | `boolean` | `false` | Whether the field is disabled and cannot be opened | | error | `ReactNode` | `undefined` | Error message or truthy value that puts the field in an error state | | showSearch | `boolean` | `false` | Whether to show a search field at the top of the dropdown | | useFullWidthItems | `boolean` | `false` | Whether option rows stretch to the full width of the dropdown | | itemCharacterLimit | `string` | `"64ch"` | Maximum width of option labels before they truncate | | maxHeight | `string` | `undefined` | Maximum height of the dropdown menu (for example "300px" or "50vh") | | allowCreateOption | `boolean` | `false` | Whether users can create a new option from the current search text | | noAvailableOptions | `boolean \| function` | `true` | What to render when nothing matches. true shows the default empty message. A function receives \{ search, close }. | | defaultOpen | `boolean` | `false` | Whether the dropdown is open on first render | | onOpenChange | `(open: boolean) => void` | `undefined` | Called when the dropdown opens or closes | ```tsx import { CheckboxMultiSelect } from '@clickhouse/click-ui' import { useState } from 'react' function Example() { const [values, setValues] = useState(['typescript']) return ( ) } ``` ### Item props Use `CheckboxMultiSelect.Item` when you pass options as children. | Prop | Type | Default value | Description | | ----------- | --------------------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------- | | value | `string` | `""` | Value stored in the selected array when this item is checked | | label | `ReactNode` | `undefined` | Option label. Use this or children, not both. | | description | `ReactNode` | `undefined` | Secondary text under the label. Also available as CheckboxMultiSelect.ItemDescription. | | disabled | `boolean` | `false` | Whether this option cannot be selected | | icon | `IconName` | `undefined` | Optional icon shown with the option | | iconDir | `"start" \| "end"` | `"end"` | Which side of the label to place the icon | | variant | `"default" \| "var1" \| "var2" \| "var3" \| "var4" \| "var5" \| "var6" \| "var7"` | `"default"` | Checkbox color variant for this option | | separator | `boolean` | `false` | Whether to render a separator after this item | ### Group props | Prop | Type | Default value | Description | | ------- | ----------- | ------------- | ------------------------------------------------- | | heading | `ReactNode` | `undefined` | Group heading shown above the items in this group | ## Quick start `onSelect` receives the full selected array, not a single value: ```tsx import { CheckboxMultiSelect } from '@clickhouse/click-ui' import { useState } from 'react' function ColumnPicker() { const [values, setValues] = useState([]) return ( ) } ``` ## Related components - **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. ```tsx import { CheckboxMultiSelect } from '@clickhouse/click-ui' import { useState } from 'react' function SourcesPicker() { const [values, setValues] = useState(['logs']) return ( Query log Metrics Application logs Includes stdout and error streams ) } ``` ### With search ```tsx import { CheckboxMultiSelect } from '@clickhouse/click-ui' import { useState } from 'react' function RegionPicker() { const [values, setValues] = useState([]) return ( ) } ``` ### Checkbox variants Each item can use the same `variant` values as `Checkbox`. ```tsx import { CheckboxMultiSelect } from '@clickhouse/click-ui' import { useState } from 'react' function VariantPicker() { const [values, setValues] = useState(['var1']) return ( Variant 1 Variant 2 ) } ``` ### Error and disabled ```tsx import { CheckboxMultiSelect, Container } from '@clickhouse/click-ui' ```