Web Components Checkbox Component

The Web Components Checkbox is a component that lets you add checkboxes to your Web Components 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 Web Components checkbox component and ability to use it with forms.

Live Demo

Anatomy

The Web Components Checkbox renders a selectable control with an optional label.

The Web Components 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 Web Components Checkbox, follow the Ignite UI for Web Components Getting Started topic for the basic project setup, then install or register the component for your target platform.

Using the igniteui-webcomponents package, install the package before importing and registering the Checkbox:

npm install igniteui-webcomponents

Then import the Checkbox, its theme CSS, and register the component module:

import { defineComponents, IgcCheckboxComponent } from "igniteui-webcomponents";
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcCheckboxComponent);

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

<igc-checkbox></igc-checkbox>

Usage

At its core, the Checkbox 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):

<igc-checkbox label-position="before">Label</igc-checkbox>

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>
<igc-checkbox aria-labelledby="checkbox-label"></igc-checkbox>

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.

<igc-checkbox checked></igc-checkbox>

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

<igc-checkbox indeterminate></igc-checkbox>

You can use the disabled attribute to disable the Checkbox.

<igc-checkbox disabled></igc-checkbox>

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

<igc-checkbox invalid></igc-checkbox>

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

<igc-checkbox required></igc-checkbox>

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 Web Components Checkbox uses CSS parts and CSS variables to customize its appearance.

Sass Theming

Use the Ignite UI for Web Components 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 Web Components 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";

<igc-checkbox class="![--tick-color:var(--ig-secondary-500)]"></igc-checkbox>

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

Accessibility

The Web Components 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 Web Components 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 Web Components Checkbox requires a theme stylesheet to apply its visual styling. See the framework-specific setup in Getting Started.

Additional Resources

Use the following Web Components resources for API details and project support:

• Ignite UI for Web Components Forums
• Ignite UI for Web Components GitHub

Related Components

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

• Switch

FAQ

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