Checkbox

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

Usage

1import { Checkbox } from '@lenso/ui';

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4
5export function Basic() {6  return (7    <Checkbox name="basic-terms">8      <Checkbox.Content>9        <Checkbox.Control>10          <Checkbox.Indicator />11        </Checkbox.Control>12        Accept terms and conditions13      </Checkbox.Content>14    </Checkbox>15  );16}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Anatomy

1import { Checkbox, Description, FieldError } from '@lenso/ui';2
3export default () => (4  <Checkbox>5    <Checkbox.Content>6      <Checkbox.Control>7        <Checkbox.Indicator />8      </Checkbox.Control>9      Label {/* plain text — the clickable label + accessible name */}10    </Checkbox.Content>11    <Description /> {/* Optional — field-level help text */}12    <FieldError /> {/* Optional — validation message */}13  </Checkbox>14);

Examples

Variants

The Checkbox component supports two visual variants:

primary (default) - Standard styling with default background, suitable for most use cases
secondary - Lower emphasis variant, suitable for use in Surface components

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox, Description, TextField } from "@lenso/ui";4import { checkboxSupportingStyles } from "@lenso/tokens/checkbox";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", flexDirection: "column", gap: "1rem" },8  section: { display: "flex", flexDirection: "column", gap: ".5rem" },9  heading: { fontSize: ".875rem", fontWeight: 500, color: "var(--muted)" },10});11export function Variants() {12  return (13    <div {...stylex.props(styles.root)}>14      <div {...stylex.props(styles.section)}>15        <p {...stylex.props(styles.heading)}>Primary variant</p>16        <TextField>17          <Checkbox id="primary" name="primary" variant="primary">18            <Checkbox.Content>19              <Checkbox.Control>20                <Checkbox.Indicator />21              </Checkbox.Control>22              Primary checkbox23            </Checkbox.Content>24            <Description xstyle={checkboxSupportingStyles.direct}>25              Standard styling with default background26            </Description>27          </Checkbox>28        </TextField>29      </div>30      <div {...stylex.props(styles.section)}>31        <p {...stylex.props(styles.heading)}>Secondary variant</p>32        <TextField>33          <Checkbox id="secondary" name="secondary" variant="secondary">34            <Checkbox.Content>35              <Checkbox.Control>36                <Checkbox.Indicator />37              </Checkbox.Control>38              Secondary checkbox39            </Checkbox.Content>40            <Description xstyle={checkboxSupportingStyles.direct}>41              Lower emphasis variant for use in surfaces42            </Description>43          </Checkbox>44        </TextField>45      </div>46    </div>47  );48}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Full Rounded

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4import { labelStyles } from "@lenso/tokens/label";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", flexDirection: "column", gap: "1.5rem" },8  section: { display: "flex", flexDirection: "column", gap: ".75rem" },9  label: { color: "var(--muted)" },10  smallIndicator: { "--checkbox-checkmark-size": ".5rem" },11  extraLargeIndicator: { "--checkbox-checkmark-size": "1rem" },12  small: {13    width: ".75rem",14    height: ".75rem",15    borderRadius: "9999px",16    "::before": { borderRadius: "9999px" },17  },18  medium: {19    width: "1rem",20    height: "1rem",21    borderRadius: "9999px",22    "::before": { borderRadius: "9999px" },23  },24  large: {25    width: "1.25rem",26    height: "1.25rem",27    borderRadius: "9999px",28    "::before": { borderRadius: "9999px" },29  },30  extraLarge: {31    width: "1.5rem",32    height: "1.5rem",33    borderRadius: "9999px",34    "::before": { borderRadius: "9999px" },35  },36});37export function FullRounded() {38  return (39    <div {...stylex.props(styles.root)}>40      <div {...stylex.props(styles.section)}>41        <span {...stylex.props(labelStyles.label, styles.label)}>Rounded checkboxes</span>42        <Checkbox name="small-rounded">43          <Checkbox.Content>44            <Checkbox.Control xstyle={styles.small}>45              <Checkbox.Indicator xstyle={styles.smallIndicator} />46            </Checkbox.Control>47            Small size48          </Checkbox.Content>49        </Checkbox>50      </div>51      <div {...stylex.props(styles.section)}>52        <Checkbox name="default-rounded">53          <Checkbox.Content>54            <Checkbox.Control xstyle={styles.medium}>55              <Checkbox.Indicator />56            </Checkbox.Control>57            Default size58          </Checkbox.Content>59        </Checkbox>60      </div>61      <div {...stylex.props(styles.section)}>62        <Checkbox name="large-rounded">63          <Checkbox.Content>64            <Checkbox.Control xstyle={styles.large}>65              <Checkbox.Indicator />66            </Checkbox.Control>67            Large size68          </Checkbox.Content>69        </Checkbox>70      </div>71      <div {...stylex.props(styles.section)}>72        <Checkbox name="xl-rounded">73          <Checkbox.Content>74            <Checkbox.Control xstyle={styles.extraLarge}>75              <Checkbox.Indicator xstyle={styles.extraLargeIndicator} />76            </Checkbox.Control>77            Extra large size78          </Checkbox.Content>79        </Checkbox>80      </div>81    </div>82  );83}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Disabled

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox, Description, TextField } from "@lenso/ui";4import { checkboxSupportingStyles } from "@lenso/tokens/checkbox";5export function Disabled() {6  return (7    <TextField>8      <Checkbox disabled id="feature" aria-describedby="feature-help">9        <Checkbox.Content>10          <Checkbox.Control>11            <Checkbox.Indicator />12          </Checkbox.Control>13          Premium Feature14        </Checkbox.Content>15        <Description id="feature-help" xstyle={checkboxSupportingStyles.direct}>16          This feature is coming soon17        </Description>18      </Checkbox>19    </TextField>20  );21}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

External Label

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4import { labelStyles } from "@lenso/tokens/label";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({ root: { display: "flex", alignItems: "center", gap: ".75rem" } });7export function ExternalLabel() {8  return (9    <div {...stylex.props(styles.root)}>10      <Checkbox id="label-marketing">11        <Checkbox.Content>12          <Checkbox.Control>13            <Checkbox.Indicator />14          </Checkbox.Control>15        </Checkbox.Content>16      </Checkbox>17      <label {...stylex.props(labelStyles.label)} htmlFor="label-marketing">18        Send me marketing emails19      </label>20    </div>21  );22}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

With Description

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox, Description, TextField } from "@lenso/ui";4import { checkboxSupportingStyles } from "@lenso/tokens/checkbox";5export function WithDescription() {6  return (7    <TextField>8      <Checkbox name="description-notifications" aria-describedby="description-notifications-help">9        <Checkbox.Content>10          <Checkbox.Control>11            <Checkbox.Indicator />12          </Checkbox.Control>13          Email notifications14        </Checkbox.Content>15        <Description id="description-notifications-help" xstyle={checkboxSupportingStyles.direct}>16          Get notified when someone mentions you in a comment17        </Description>18      </Checkbox>19    </TextField>20  );21}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Default Selected

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4export function DefaultSelected() {5  return (6    <Checkbox defaultChecked id="default-notifications">7      <Checkbox.Content>8        <Checkbox.Control>9          <Checkbox.Indicator />10        </Checkbox.Control>11        Enable email notifications12      </Checkbox.Content>13    </Checkbox>14  );15}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Invalid

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox, FieldError, TextField } from "@lenso/ui";4import { checkboxSupportingStyles } from "@lenso/tokens/checkbox";5export function Invalid() {6  return (7    <TextField invalid>8      <Checkbox required name="agreement">9        <Checkbox.Content>10          <Checkbox.Control>11            <Checkbox.Indicator />12          </Checkbox.Control>13          I agree to the terms14        </Checkbox.Content>15        <FieldError16          match17          xstyle={[checkboxSupportingStyles.direct, checkboxSupportingStyles.error]}18        >19          You must accept the terms to continue20        </FieldError>21      </Checkbox>22    </TextField>23  );24}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Controlled

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4import { useState } from "react";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  root: { display: "flex", flexDirection: "column", gap: ".75rem" },8  status: { fontSize: ".875rem", color: "var(--muted)" },9  strong: { fontWeight: 500 },10});11export function Controlled() {12  const [isSelected, setIsSelected] = useState(true);13  return (14    <div {...stylex.props(styles.root)}>15      <Checkbox id="email-notifications" checked={isSelected} onCheckedChange={setIsSelected}>16        <Checkbox.Content>17          <Checkbox.Control>18            <Checkbox.Indicator />19          </Checkbox.Control>20          Email notifications21        </Checkbox.Content>22      </Checkbox>23      <p {...stylex.props(styles.status)}>24        Status: <span {...stylex.props(styles.strong)}>{isSelected ? "Enabled" : "Disabled"}</span>25      </p>26    </div>27  );28}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Indeterminate

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox, Description, TextField } from "@lenso/ui";4import { checkboxSupportingStyles } from "@lenso/tokens/checkbox";5import { useState } from "react";6export function Indeterminate() {7  const [isIndeterminate, setIsIndeterminate] = useState(true);8  const [isSelected, setIsSelected] = useState(false);9  return (10    <TextField>11      <Checkbox12        id="select-all"13        indeterminate={isIndeterminate}14        checked={isSelected}15        onCheckedChange={(selected) => {16          setIsSelected(selected);17          setIsIndeterminate(false);18        }}19      >20        <Checkbox.Content>21          <Checkbox.Control>22            <Checkbox.Indicator />23          </Checkbox.Control>24          Select all25        </Checkbox.Content>26        <Description xstyle={checkboxSupportingStyles.direct}>27          Shows indeterminate state (dash icon)28        </Description>29      </Checkbox>30    </TextField>31  );32}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Form Integration

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Button, Checkbox } from "@lenso/ui";4import type { FormEvent } from "react";5import * as stylex from "@stylexjs/stylex";6const styles = stylex.create({7  form: { display: "flex", flexDirection: "column", gap: "1rem" },8  items: { display: "flex", flexDirection: "column", gap: ".75rem" },9  submit: { marginTop: "1rem" },10});11export function Form() {12  const handleSubmit = (e: FormEvent<HTMLFormElement>) => {13    e.preventDefault();14    const formData = new FormData(e.currentTarget);15    alert(16      `Form submitted with:\n${Array.from(formData.entries())17        .map(([key, value]) => `${key}: ${value}`)18        .join("\n")}`,19    );20  };21  return (22    <form {...stylex.props(styles.form)} onSubmit={handleSubmit}>23      <div {...stylex.props(styles.items)}>24        <Checkbox name="notifications" value="on">25          <Checkbox.Content>26            <Checkbox.Control>27              <Checkbox.Indicator />28            </Checkbox.Control>29            Enable notifications30          </Checkbox.Content>31        </Checkbox>32        <Checkbox defaultChecked name="newsletter" value="on">33          <Checkbox.Content>34            <Checkbox.Control>35              <Checkbox.Indicator />36            </Checkbox.Control>37            Subscribe to newsletter38          </Checkbox.Content>39        </Checkbox>40        <Checkbox name="marketing" value="on">41          <Checkbox.Content>42            <Checkbox.Control>43              <Checkbox.Indicator />44            </Checkbox.Control>45            Receive marketing updates46          </Checkbox.Content>47        </Checkbox>48      </div>49      <Button xstyle={styles.submit} size="sm" type="submit" variant="primary">50        Submit51      </Button>52    </form>53  );54}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Render Props

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox, Description, TextField } from "@lenso/ui";4import { checkboxSupportingStyles } from "@lenso/tokens/checkbox";5export function RenderProps() {6  return (7    <TextField>8      <Checkbox9        id="render-props-terms"10        render={(props, { checked }) => (11          <span {...props}>12            <Checkbox.Content>13              <Checkbox.Control>14                <Checkbox.Indicator />15              </Checkbox.Control>16              {checked ? "Terms accepted" : "Accept terms"}17            </Checkbox.Content>18            <Description xstyle={checkboxSupportingStyles.direct}>19              {checked ? "Thank you for accepting" : "Please read and accept the terms"}20            </Description>21          </span>22        )}23      />24    </TextField>25  );26}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Render Function

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4export function RenderFunction() {5  return (6    <Checkbox render={(props) => <div {...props} data-custom="bar" />}>7      <Checkbox.Content>8        <Checkbox.Control>9          <Checkbox.Indicator />10        </Checkbox.Control>11        Accept terms and conditions12      </Checkbox.Content>13    </Checkbox>14  );15}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Custom Indicator

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({ root: { display: "flex", gap: "1rem" } });6export function CustomIndicator() {7  return (8    <div {...stylex.props(styles.root)}>9      <Checkbox defaultChecked name="heart">10        <Checkbox.Content>11          <Checkbox.Control>12            <Checkbox.Indicator13              render={(props, { checked }) => (14                <span {...props}>15                  {checked ? (16                    <svg aria-hidden="true" fill="currentColor" viewBox="0 0 24 24">17                      <path d="M12.62 20.81c-.34.12-.9.12-1.24 0C8.48 19.82 2 15.69 2 8.69 2 5.6 4.49 3.1 7.56 3.1c1.82 0 3.43.88 4.44 2.24a5.53 5.53 0 0 1 4.44-2.24C19.51 3.1 22 5.6 22 8.69c0 7-6.48 11.13-9.38 12.12Z" />18                    </svg>19                  ) : null}20                </span>21              )}22            />23          </Checkbox.Control>24          Heart25        </Checkbox.Content>26      </Checkbox>27      <Checkbox defaultChecked name="plus">28        <Checkbox.Content>29          <Checkbox.Control>30            <Checkbox.Indicator31              render={(props, { checked }) => (32                <span {...props}>33                  {checked ? (34                    <svg aria-hidden="true" fill="none" viewBox="0 0 24 24">35                      <path36                        d="M6 12H18"37                        stroke="currentColor"38                        strokeLinecap="round"39                        strokeLinejoin="round"40                        strokeWidth="3"41                      />42                      <path43                        d="M12 18V6"44                        stroke="currentColor"45                        strokeLinecap="round"46                        strokeLinejoin="round"47                        strokeWidth="3"48                      />49                    </svg>50                  ) : null}51                </span>52              )}53            />54          </Checkbox.Control>55          Plus56        </Checkbox.Content>57      </Checkbox>58      <Checkbox indeterminate name="indeterminate">59        <Checkbox.Content>60          <Checkbox.Control>61            <Checkbox.Indicator62              render={(props, { indeterminate }) => (63                <span {...props}>64                  {indeterminate ? (65                    <svg66                      aria-hidden="true"67                      stroke="currentColor"68                      strokeWidth={3}69                      viewBox="0 0 24 24"70                    >71                      <line x1="21" x2="3" y1="12" y2="12" />72                    </svg>73                  ) : null}74                </span>75              )}76            />77          </Checkbox.Control>78          Indeterminate79        </Checkbox.Content>80      </Checkbox>81    </div>82  );83}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Customization

Tailwind CSS

1"use client";2/** Adapted from HeroUI v3.2.6. SPDX-License-Identifier: Apache-2.0 */3import { Checkbox } from "@lenso/ui";4import * as stylex from "@stylexjs/stylex";5const styles = stylex.create({6  control: {7    backgroundColor: "var(--success-soft)",8    "::before": {9      backgroundColor: {10        default: "var(--success)",11        ":is([data-slot='checkbox']:hover *)": "var(--success)",12        ":is([data-slot='checkbox'][data-invalid] *)": "var(--success)",13      },14    },15  },16  indicator: { color: "var(--success-foreground)" },17});18export function CustomStyles() {19  return (20    <Checkbox id="custom">21      <Checkbox.Content>22        <Checkbox.Control xstyle={styles.control}>23          <Checkbox.Indicator xstyle={styles.indicator} />24        </Checkbox.Control>25        Custom styled checkbox26      </Checkbox.Content>27    </Checkbox>28  );29}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

Global CSS

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

1@layer components {2  .checkbox {3    @apply inline-flex gap-3 items-center;4  }5
6  .checkbox__control {7    @apply size-5 border-2 border-gray-400 rounded data-[selected=true]:bg-blue-500 data-[selected=true]:border-blue-500;8
9    /* Animated background indicator */10    &::before {11      @apply bg-accent pointer-events-none absolute inset-0 z-0 origin-center scale-50 rounded-md opacity-0 content-[''];12
13      transition:14        scale 200ms linear,15        opacity 200ms linear,16        background-color 200ms ease-out;17    }18
19    /* Show indicator when selected */20    &[data-selected="true"]::before {21      @apply scale-100 opacity-100;22    }23  }24
25  .checkbox__indicator {26    @apply text-white;27  }28
29  .checkbox__content {30    @apply items-center gap-3;31  }32}

Styling Reference

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

CSS Classes

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

Base Classes [!toc]

.checkbox - Base checkbox container (the field)
.checkbox__content - Clickable label wrapping the control and label text
.checkbox__control - Checkbox control box
.checkbox__indicator - Checkbox checkmark indicator

Interactive States

The checkbox supports both CSS pseudo-classes and data attributes for flexibility:

Selected: [data-selected="true"] or [aria-checked="true"] (shows checkmark and background color change)
Indeterminate: [data-indeterminate="true"] (shows indeterminate state with dash)
Invalid: [data-invalid="true"] or [aria-invalid="true"] (shows error state with danger colors)
Hover: :hover or [data-hovered="true"] on Checkbox.Control (button)
Focus: :focus-visible or [data-focus-visible="true"] on the button (shows focus ring on control)
Disabled: [data-disabled="true"] on the field (reduced opacity, including help text)
Pressed: :active or [data-pressed="true"]

API Reference

Checkbox

Inherits from React Aria CheckboxField.

Prop	Type	Default	Description
`isSelected`	`boolean`	`false`	Whether the checkbox is checked
`defaultSelected`	`boolean`	`false`	Whether the checkbox is checked by default (uncontrolled)
`isIndeterminate`	`boolean`	`false`	Whether the checkbox is in an indeterminate state
`isDisabled`	`boolean`	`false`	Whether the checkbox is disabled
`isInvalid`	`boolean`	`false`	Whether the checkbox is invalid
`isReadOnly`	`boolean`	`false`	Whether the checkbox is read only
`isRequired`	`boolean`	`false`	Whether the checkbox must be selected
`validate`	`(value: boolean) => ValidationError \| true \| null \| undefined`	-	Custom validation function
`validationBehavior`	`'native' \| 'aria'`	`'native'`	Whether to use native HTML form validation or ARIA
`variant`	`"primary" \| "secondary"`	`"primary"`	Visual variant of the component. `primary` is the default style with shadow. `secondary` is a lower emphasis variant without shadow, suitable for use in surfaces.
`name`	`string`	-	The name of the input element, used when submitting an HTML form
`value`	`string`	-	The value of the input element, used when submitting an HTML form
`onChange`	`(isSelected: boolean) => void`	-	Handler called when the checkbox value changes
`children`	`React.ReactNode \| (values: CheckboxFieldRenderProps) => React.ReactNode`	-	Checkbox content or field render prop
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, CheckboxFieldRenderProps>`	-	Overrides the default DOM element with a custom render function.

Checkbox.Content

The clickable <label> that wraps the control and label text. Put Checkbox.Control and the Label inside it; keep Description/FieldError as siblings of Checkbox.Content. For a checkbox with no label, omit the Label and pass an aria-label on Checkbox.

Prop	Type	Default	Description
`children`	`React.ReactNode \| (values: CheckboxButtonRenderProps) => React.ReactNode`	-	Button content (control + label), or a button render prop
`className`	`string \| (values: CheckboxButtonRenderProps) => string`	-	Classes applied to the clickable label

CheckboxFieldRenderProps

When using a render prop on the root Checkbox, these field-level values are provided:

Prop	Type	Description
`isSelected`	`boolean`	Whether the checkbox is currently checked
`isIndeterminate`	`boolean`	Whether the checkbox is in an indeterminate state
`isDisabled`	`boolean`	Whether the checkbox is disabled
`isReadOnly`	`boolean`	Whether the checkbox is read only
`isInvalid`	`boolean`	Whether the checkbox is invalid
`isRequired`	`boolean`	Whether the checkbox is required

CheckboxButtonRenderProps

Checkbox.Control and Checkbox.Indicator use button-level render props (isHovered, isPressed, isFocusVisible, etc.). Pass a function as Checkbox.Control children or to Checkbox.Indicator to access them.

Label

Renders an accessible label associated with form controls

CheckboxGroup

A checkbox group component for managing multiple checkbox selections

Description

Provides supplementary text for form fields and other components

Checkbox

Usage

Anatomy

Examples

Variants

Full Rounded

Disabled

External Label

With Description

Default Selected

Invalid

Controlled

Indeterminate

Form Integration

Render Props

Render Function

Custom Indicator

Customization

Tailwind CSS

Global CSS

Styling Reference

CSS Classes

Base Classes [!toc]

Interactive States

API Reference

Checkbox

Checkbox.Content

CheckboxFieldRenderProps

CheckboxButtonRenderProps

Related Components