Blazor Checkbox Component

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

Live Demo

Anatomy

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

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

Register the Ignite UI for Blazor services:

// in Program.cs file

builder.Services.AddIgniteUIBlazor();

Registering IgbCheckboxModule, the Checkbox’s client resource module, is optional: the component loads its resources when it first renders. Listing it in builder.Services.AddIgniteUIBlazor(typeof(IgbCheckboxModule)) can be used to preload resources or to support elements created only on the client (see Component Modules).

Then link the theme CSS file in the app’s host page (wwwroot/index.html in a standalone Blazor WebAssembly or Blazor Hybrid app, Pages/_Host.cshtml in a Blazor Server app, Components/App.razor in a Blazor Web App):

<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />

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

<IgbCheckbox />

Usage

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

<IgbCheckbox LabelPosition="@ToggleLabelPosition.Before">Label</IgbCheckbox>

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>
<IgbCheckbox AriaLabelledBy="checkbox-label" />

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.

<IgbCheckbox Checked="true" />

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

<IgbCheckbox Indeterminate="true" />

You can use the disabled attribute to disable the Checkbox.

<IgbCheckbox Disabled="true" />

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

<IgbCheckbox Invalid="true" />

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

<IgbCheckbox Required="true" />

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

Sass Theming

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

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

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

Accessibility

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

Additional Resources

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

• Ignite UI for Blazor Forums
• Ignite UI for Blazor GitHub

Related Components

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

• IgbSwitch

FAQ

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