BlakeUI
Getting Started
Components
Releases
Forms

CheckboxGroup

A checkbox group component for managing multiple checkbox selections

StorybookReact Aria

Completeness: styles-sufficient

The stylesheet is the whole component. There is no keyboard map beyond what the native element already does and nothing sets state at runtime that the CSS keys on, so a CSS-only port reproduces it.

Import

import { CheckboxGroup, Checkbox, Label, Description } from '@blakeui/react';

Usage

Select your interestsChoose all that apply
import {Checkbox, CheckboxGroup, Description, Label} from "@blakeui/react";

export function Basic() {
  return (
    <CheckboxGroup name="interests">

Anatomy

Import the CheckboxGroup component and access all parts using dot notation.

import {CheckboxGroup, Checkbox, Label, Description, FieldError} from '@blakeui/react';

export default () => (
  <CheckboxGroup name="interests">
    <Label />
    <Description /> {/* Optional */}
    <Checkbox value="option1">
      <Checkbox.Control>
        <Checkbox.Indicator />
      </Checkbox.Control>
      <Checkbox.Content>
        <Label />
        <Description /> {/* Optional */}
      </Checkbox.Content>
    </Checkbox>
    <FieldError /> {/* Optional */}
  </CheckboxGroup>
);

In Surface

When used inside a Surface component, use variant="secondary" to apply the lower emphasis variant suitable for surface backgrounds.

Select your interestsChoose all that apply
import {Checkbox, CheckboxGroup, Description, Label, Surface} from "@blakeui/react";

export function OnSurface() {
  return (
    <Surface className="w-full rounded-3xl p-6">

With Custom Indicator

FeaturesSelect the features you want
"use client";

import {Checkbox, CheckboxGroup, Description, Label} from "@blakeui/react";

export function WithCustomIndicator() {

Indeterminate

"use client";

import {Checkbox, CheckboxGroup, Label} from "@blakeui/react";
import {useState} from "react";

Controlled

Your skillsSelected: coding, design
"use client";

import {Checkbox, CheckboxGroup, Label} from "@blakeui/react";
import {useState} from "react";

Validation

Preferences
"use client";

import {Button, Checkbox, CheckboxGroup, FieldError, Form, Label} from "@blakeui/react";

export function Validation() {

Disabled

FeaturesFeature selection is temporarily disabled
import {Checkbox, CheckboxGroup, Description, Label} from "@blakeui/react";

export function Disabled() {
  return (
    <CheckboxGroup isDisabled name="disabled-features">

Features and Add-ons Example

Notification preferencesChoose how you want to receive updates
import {Checkbox, CheckboxGroup, Description, Label} from "@blakeui/react";
import {Bell, Comment, Envelope} from "@gravity-ui/icons";
import clsx from "clsx";

export function FeaturesAndAddOns() {

Custom Render Function

Select your interestsChoose all that apply
"use client";

import {Checkbox, CheckboxGroup, Description, Label} from "@blakeui/react";

export function CustomRenderFunction() {

Styling

Passing Tailwind CSS classes

You can customize the CheckboxGroup component:

import { CheckboxGroup, Checkbox, Label } from '@blakeui/react';

function CustomCheckboxGroup() {
  return (
    <CheckboxGroup className="gap-4" name="custom">
      <Checkbox value="option1">
        <Checkbox.Control className="border-2 border-purple-500 data-[selected=true]:bg-purple-500">
          <Checkbox.Indicator className="text-white" />
        </Checkbox.Control>
        <Checkbox.Content>
          <Label>Option 1</Label>
        </Checkbox.Content>
      </Checkbox>
    </CheckboxGroup>
  );
}

Customizing the component classes

To customize the CheckboxGroup component classes, you can use the @layer components directive.
Learn more.

A worked example is in Styling.

blakeUI follows the BEM methodology to ensure component variants and states are reusable and easy to customize.

CSS Classes

The CheckboxGroup component uses these CSS classes (View source styles):

  • .checkbox-group - Base checkbox group container

API Reference

CheckboxGroup Props

Inherits from React Aria CheckboxGroup.

PropTypeDefaultDescription
valuestring[]-The current selected values (controlled)
defaultValuestring[]-The default selected values (uncontrolled)
onChange(value: string[]) => void-Handler called when the selected values change
isDisabledbooleanfalseWhether the checkbox group is disabled
isRequiredbooleanfalseWhether the checkbox group is required
isReadOnlybooleanfalseWhether the checkbox group is read only
isInvalidbooleanfalseWhether the checkbox group is in an invalid state
namestring-The name of the checkbox group, used when submitting an HTML form
childrenReact.ReactNode | (values: CheckboxGroupRenderProps) => React.ReactNode-Checkbox group content or render prop
renderDOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxGroupRenderProps>-Overrides the default DOM element with a custom render function.

CheckboxGroupRenderProps

When using the render prop pattern, these values are provided:

PropTypeDescription
valuestring[]The currently selected values
isDisabledbooleanWhether the checkbox group is disabled
isReadOnlybooleanWhether the checkbox group is read only
isInvalidbooleanWhether the checkbox group is in an invalid state
isRequiredbooleanWhether the checkbox group is required

Checkbox

Checkboxes allow users to select multiple items from a list of individual items, or to mark one individual item as selected.

Description

Provides supplementary text for form fields and other components

On this page

ImportUsageAnatomyIn SurfaceWith Custom IndicatorIndeterminateControlledValidationDisabledFeatures and Add-ons ExampleCustom Render FunctionStylingPassing Tailwind CSS classesCustomizing the component classesCSS ClassesAPI ReferenceCheckboxGroup PropsCheckboxGroupRenderProps