Form checkbox

Lets users select zero, one, or multiple independent options in a form.

On this page

This docs is LLM-friendly and available as clean Markdown.

Supported browser agents can also use WebMCP to search, read, and open these docs. Learn more

Usage

import {
  GlFormCheckbox,
  GlFormCheckboxGroup,
} from "gitlab-ui-react/form-checkbox";

<GlFormCheckboxGroup
  aria-label="Notifications"
  defaultValue={["email"]}
  name="notifications">
  <GlFormCheckbox value="email">Email notifications</GlFormCheckbox>
  <GlFormCheckbox value="browser">Browser notifications</GlFormCheckbox>
</GlFormCheckboxGroup>

Default

Use a checkbox for an independent boolean choice. Its visible text is rendered in a native label associated with the checkbox input.

Single checkbox

Storybook

Receive notifications

import { GlFormCheckbox } from "gitlab-ui-react/form-checkbox";

export default function FormCheckboxExample() {
  return (
    <GlFormCheckbox defaultChecked value="notifications">
      Receive notifications
    </GlFormCheckbox>
  );
}

Checkbox group

Use GlFormCheckboxGroup when users can select more than one option from a related set. A group shares its name, state, disabled state, and selected value array with child checkboxes.

Checkbox group

Storybook

Notification channels

Browser

Mobile

import {
  GlFormFieldLegend,
  GlFormFieldSet,
} from "gitlab-ui-react/form-field";
import {
  GlFormCheckbox,
  GlFormCheckboxGroup,
} from "gitlab-ui-react/form-checkbox";

export default function FormCheckboxGroupExample() {
  return (
    <GlFormFieldSet>
      <GlFormFieldLegend id="notification-channels">
        Notification channels
      </GlFormFieldLegend>
      <GlFormCheckboxGroup
        aria-label="Notification channels"
        defaultValue={["email"]}
        name="notification-channels">
        <GlFormCheckbox value="email">Email</GlFormCheckbox>
        <GlFormCheckbox value="browser">Browser</GlFormCheckbox>
        <GlFormCheckbox value="mobile">Mobile</GlFormCheckbox>
      </GlFormCheckboxGroup>
    </GlFormFieldSet>
  );
}

States and help text

Use indeterminate for a parent whose descendants have mixed values. Help text clarifies an option, while disabled state preserves a value that cannot currently be changed.

Checkbox states

Storybook

Partially selected

Unavailable option

Include optional updates

You can change this later.

import { GlFormCheckbox } from "gitlab-ui-react/form-checkbox";

export default function FormCheckboxStatesExample() {
  return (
    <div className="flex flex-col gap-3">
      <GlFormCheckbox indeterminate>Partially selected</GlFormCheckbox>
      <GlFormCheckbox disabled>Unavailable option</GlFormCheckbox>
      <GlFormCheckbox help="You can change this later.">
        Include optional updates
      </GlFormCheckbox>
    </div>
  );
}

Accessibility

Give every checkbox a concise visible label. Use ariaLabel or ariaLabelledby only when visible label content is unavailable.
Wrap a related set in GlFormFieldSet with GlFormFieldLegend, and give GlFormCheckboxGroup its own accessible name with aria-label.
Use checkboxes only when zero, one, or multiple choices are valid. Use radio buttons when exactly one option is expected.
Pair state={false} with visible validation feedback and associate it through aria-describedby.

API

Both components forward supported native attributes. A checkbox inside a group takes its selection, name, required, disabled, and validation state from the group.

`GlFormCheckbox`

Prop	Description	Default
`checked`	Controls the checked state outside a group.	—
`defaultChecked`	Sets the initial uncontrolled checked state.	`false`
`onCheckedChange`	Reports the next checked state after user interaction.	—
`value`	Sets the native value and the option value inside a group.	`true`
`indeterminate`	Shows the mixed selection state outside a group.	`false`
`disabled`	Disables the checkbox.	`false`
`required`	Marks a named checkbox as required.	`false`
`state`	Sets valid, invalid, or neutral appearance.	`null`
`help`	Renders help content under the label.	—

`GlFormCheckboxGroup`

Prop	Description	Default
`value`	Controls the selected option values.	—
`defaultValue`	Sets the initial uncontrolled selected values.	`[]`
`onValueChange`	Reports the next selected value array.	—
`options`	Generates checkboxes from strings, numbers, or option objects.	`[]`
`name`	Sets the shared name for child checkboxes.	Generated group ID
`disabled`	Disables every checkbox in the group.	`false`
`required`	Marks grouped checkboxes as required.	`false`
`state`	Sets group and child validation appearance.	`null`

Usage

Default

Checkbox group

States and help text

Accessibility

API

GlFormCheckbox

GlFormCheckboxGroup

Related resources

`GlFormCheckbox`

`GlFormCheckboxGroup`