CheckboxGroupInput

Multi-select input rendered as a list (column or row) of checkboxes.

Installation

pnpm dlx shadcn@latest add @shadmin/checkbox-group-input

Usage

In addition to the source, <CheckboxGroupInput> requires one prop: the choices listing the possible values.

import { CheckboxGroupInput } from "@/components/admin";
 
<CheckboxGroupInput
  source="tags"
  choices={[
    { id: "tech", name: "Tech" },
    { id: "lifestyle", name: "Lifestyle" },
    { id: "people", name: "People" },
  ]}
/>;

By default, the possible choices are built from the choices prop, using:

the id field as the option value,
the name field as the option text.

The form value for the source must be an array of selected ids, e.g.:

const record = {
  id: 1,
  name: "Hello, World",
  tags: ["tech", "lifestyle"],
};

Props

Prop	Required	Type	Default	Description
`source`	Required*	`string`	-	Field name (inferred in ReferenceArrayInput)
`choices`	Required*	`Object[]`	-	List of items to display as checkboxes. Required if not inside a ReferenceArrayInput.
`className`	Optional	`string`	-	Wrapper classes
`defaultValue`	Optional	`any[]`	`[]`	The default value for the input
`disabled`	Optional	`boolean`	`false`	If true, every checkbox is disabled
`disableValue`	Optional	`string`	`disabled`	Field marking disabled choices
`format`	Optional	`Function`	-	Callback taking the value from the form state, and returning the input value.
`helperText`	Optional	`string` \| `ReactNode`	-	The helper text to display below the input
`label`	Optional	`string` \| `ReactNode` \| `false`	Inferred	The label to display above the input
`labelPlacement`	Optional	`"end" \| "start" \| "top" \| "bottom"`	`"end"`	Position of each checkbox's label relative to the checkbox box
`options`	Optional	`ComponentProps<typeof Checkbox>`	-	Props forwarded to each underlying `<Checkbox>` (e.g. `className`, `disabled`)
`optionText`	Optional	`string` \| `Function` \| `Component`	`name`	Field name of the record to display as the option text, or function/component that renders it
`optionValue`	Optional	`string`	`id`	Field name of the record containing the value to use as the form value
`parse`	Optional	`Function`	-	Callback taking the value from the input, and returning the value to be stored in the form state
`row`	Optional	`boolean`	`false`	Horizontal layout
`translateChoice`	Optional	`boolean`	`true`	Whether the choices should be translated
`validate`	Optional	`Function` \| `Function[]`	-	An array of validation functions or a single validation function

* source and choices are optional inside <ReferenceArrayInput>.

`options`

Props spread onto every <Checkbox> in the group. Use this to apply a shared className, change the checkbox size, or forward any other prop that shadcn/ui's <Checkbox> accepts.

<CheckboxGroupInput
  source="tags"
  choices={choices}
  options={{ className: "size-5 rounded-full" }}
/>

`labelPlacement`

Controls where each checkbox's text label appears relative to the checkbox box. Accepts "end" (default, label to the right), "start" (label to the left), "top" (label above), or "bottom" (label below).

<CheckboxGroupInput source="tags" choices={choices} labelPlacement="top" />

`row`

Use the row prop to display the checkboxes horizontally instead of vertically.

<CheckboxGroupInput row source="tags" choices={choices} />

`choices`

The list of choices must be an array of objects with at least two fields: one to use for the name, and the other to use for the value. By default, <CheckboxGroupInput> will use the id and name fields.

const choices = [
  { id: "tech", name: "Tech" },
  { id: "lifestyle", name: "Lifestyle" },
  { id: "people", name: "People" },
];
<CheckboxGroupInput source="tags" choices={choices} />;

If the choices have different keys, use optionText and optionValue:

const choices = [
  { _id: "tech", label: "Tech" },
  { _id: "lifestyle", label: "Lifestyle" },
  { _id: "people", label: "People" },
];
 
<CheckboxGroupInput
  source="tags"
  choices={choices}
  optionText="label"
  optionValue="_id"
/>;

The choices are translated by default, so you can use translation identifiers as choices:

const choices = [
  { id: "tech", name: "myroot.tags.tech" },
  { id: "lifestyle", name: "myroot.tags.lifestyle" },
  { id: "people", name: "myroot.tags.people" },
];

You can opt out of this translation by setting the translateChoice prop to false.

To fetch the options from another resource, wrap <CheckboxGroupInput> in a <ReferenceArrayInput>:

<ReferenceArrayInput source="tag_ids" reference="tags">
  <CheckboxGroupInput />
</ReferenceArrayInput>

`disableValue`

You can disable some choices by setting a disabled field to true (or by passing a custom field name with the disableValue prop):

const choices = [
  { id: "tech", name: "Tech" },
  { id: "lifestyle", name: "Lifestyle" },
  { id: "people", name: "People", disabled: true },
];
<CheckboxGroupInput source="tags" choices={choices} />;

Alternatives

Consider the following alternatives for selecting multiple values from a list:

<SelectArrayInput> for a dropdown multi-select
<AutocompleteArrayInput> for a searchable autocomplete