React Checkbox Component

The React Checkbox is a component that lets you add checkboxes to your React apps. It behaves as a standard HTML checkbox, enabling users to select basic checked and unchecked states or an additional indeterminate state. You also get full control over the styling of the React checkbox component and ability to use it with forms.

Live Demo

Anatomy

The React Checkbox renders a selectable control with an optional label.

The React Checkbox consists of an indicator and optional label content. Set the label position when the label should appear before or after the indicator.

Checkbox
├── Checkbox Indicator
└── Label (optional)

Getting Started

To use the React Checkbox, follow the Ignite UI for React Getting Started topic for the basic project setup, then install or register the component for your target platform.

Using the **** package, install the package before importing the Checkbox wrapper:

npm install igniteui-react

Then import the React Checkbox wrapper and the theme CSS:

import { IgrCheckbox } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

After registration, render the IgrCheckbox with the platform-specific element or wrapper:

<IgrCheckbox></IgrCheckbox>

Usage

At its core, the IgrCheckbox lets users choose between selected and unselected states, with support for an indeterminate state when an option represents a partial selection.

You can specify if the label should be positioned before or after the checkbox toggle by setting the LabelPosition attribute of the checkbox. Allowed values are before and after (default):

<IgrCheckbox labelPosition="before"></IgrCheckbox>

The checkbox can also be labelled by elements external to the checkbox. In this case, the user is given full control to position and style the label in accordance with their needs.

  <span id="checkbox-label">Label</span>
  <IgrCheckbox aria-labelledby="checkbox-label" labelPosition="before"></IgrCheckbox>

States

The Checkbox supports different state-related attributes. You can use the checked attribute to set the initial state of the checkbox to on or off.

<IgrCheckbox checked={true}></IgrCheckbox>

You can use the indeterminate attribute to set the checkbox’s value to neither true nor false.

<IgrCheckbox indeterminate={true}></IgrCheckbox>

You can use the disabled attribute to disable the Checkbox.

<IgrCheckbox disabled={true}></IgrCheckbox>

You can use the invalid attribute to mark the Checkbox as invalid.

<IgrCheckbox invalid={true}></IgrCheckbox>

You can use the required property to mark the Checkbox as required.

<IgrCheckbox required={true}></IgrCheckbox>

Do/Don’t

When many Checkboxes are necessary, arrange them in a column group so users can quickly scan the list. Fewer Checkboxes may be arranged on a single line next to each other, but avoid arranging them in multiple columns.

Properties

The following properties cover the main Checkbox configuration options documented on this page. See the full API reference for the complete generated list.

Styling

The React Checkbox uses CSS parts and CSS variables to customize its appearance.

Sass Theming

Use the Ignite UI for React theme system to style the Checkbox consistently with the rest of your application. Verify the available Sass theme parameters in the API documentation before adding a custom theme.

CSS Variables

Use the following styling properties to customize the Checkbox indicator and selected-state appearance:

Style Parts

Use the following CSS parts to target the Checkbox structure:

Custom Styling

The following selectors customize the Checkbox indicator color and selected-state fill:

igc-checkbox::part(indicator) {
  --tick-color: var(--ig-secondary-500-contrast); /* check icon color */
}

igc-checkbox::part(control checked)::after {
  --fill-color: var(--ig-secondary-500); /* checkbox background color */
}

Styling with Tailwind

You can style the React Checkbox with the custom Tailwind utility classes from igniteui-theming. Make sure to set up Tailwind first, then import the Ignite UI utilities in your global stylesheet:

@import "tailwindcss";
@import "igniteui-theming/tailwind/utilities/material.css";

<IgrCheckbox className="![--tick-color:var(--ig-secondary-500)]" />

The exclamation mark (!) gives the Tailwind utility precedence over the Checkbox’s default theme styles.

Accessibility

The React Checkbox provides a selectable control with a label and state that must remain understandable for keyboard and assistive technology users.

Keyboard Interaction

The Checkbox uses the keyboard behavior provided by its rendered control. A disabled Checkbox is not keyboard interactive, and the Space key changes its checked state.

Use the keyboard interaction provided by the Checkbox and verify the focus and state-change behavior for the target platform.

Screen Readers / ARIA

The Checkbox exposes its checked state, disabled state, and, when configured, required, invalid, and indeterminate states through the semantics of its rendered control.

• Provide meaningful label content for every Checkbox so assistive technology users can identify its purpose.
• When the label is outside the component, connect it with the supported labelling mechanism and verify the announcement in the target platform.
• Preserve the Checkbox state semantics when customizing or wrapping the control.
• Change event handlers report state changes; they do not replace the accessible name or state.

The checked, unchecked, required, invalid, disabled, and indeterminate states must remain available to assistive technology through the component’s supported semantics. Verify the rendered announcement against the platform API documentation.

Accessibility Compliance

Verify the rendered React Checkbox against the accessibility requirements of the application.

Your responsibilities:

• Give every Checkbox a meaningful accessible name.
• Keep focus visible and preserve sufficient contrast when customizing the Checkbox theme.
• Ensure required, invalid, disabled, and indeterminate states are also communicated when visual styling alone is insufficient.
• Test the rendered Checkbox with keyboard navigation and supported assistive technologies.

API References

Dependencies

The React Checkbox requires a theme stylesheet to apply its visual styling. See the framework-specific setup in Getting Started.

Additional Resources

Use the following React resources for API details and project support:

• Ignite UI for React Forums
• Ignite UI for React GitHub

Related Components

The React Checkbox is intended for selectable form options. Use the following related component when you need an immediate on/off action instead:

• IgrSwitch

FAQ

These frequently asked questions cover common React Checkbox selection, accessibility, form, and validation scenarios.