SummitUI Logo SummitUI
Checkbox
Component

Checkbox

A control that allows the user to toggle between checked and not checked.

Demo

Features

  • Three states: checked, unchecked, and indeterminate
  • Keyboard navigation (Space to toggle)
  • Controlled and uncontrolled modes
  • Support for HTML forms (hidden input)
  • Grouping capabilities via CheckboxGroup
  • WCAG compliant with proper ARIA attributes

Installation

bash
dotnet add package SummitUI

Anatomy

Import the components and structure them as follows:

razor
<CheckboxRoot>
    <CheckboxIndicator>
        <span>✓</span>
    </CheckboxIndicator>
</CheckboxRoot>

Sub-components

CheckboxRoot

The root checkbox component containing the button element.

CheckboxIndicator

Renders when the checkbox is in a checked or indeterminate state.

CheckboxGroup

A wrapper for managing a group of checkboxes.

CheckboxGroupLabel

Accessible label for the checkbox group.

API Reference

CheckboxRoot

Property Type Default Description
Checked bool? null Controlled checked state
DefaultChecked bool false Default checked state for uncontrolled mode
CheckedChanged EventCallback<bool> - Callback when checked state changes
Indeterminate bool false Controlled indeterminate state
IndeterminateChanged EventCallback<bool> - Callback when indeterminate state changes
Disabled bool false Prevents interaction with the checkbox
Required bool false Indicates checkbox must be checked for form submission
Name string? null Form field name for hidden input
Value string? "on" Value submitted with form data
AriaLabel string? null Accessible label for the checkbox when not wrapped in a label element

CheckboxIndicator

Property Type Default Description
ForceMount bool false Always render in DOM (useful for CSS animations)
ChildContent RenderFragment? - Content to render when checked or indeterminate

CheckboxGroup

Property Type Default Description
Values IReadOnlyList<string>? null Controlled values of checked items
DefaultValues IReadOnlyList<string>? null Default values for uncontrolled mode
ValuesChanged EventCallback<IReadOnlyList<string>> - Callback when values change
Disabled bool false Disable entire group
Name string? null Form name for hidden inputs

CheckboxGroupLabel

Property Type Default Description
ChildContent RenderFragment? - Label content for the checkbox group

Examples

Basic Usage

razor
<CheckboxRoot DefaultChecked="true">
    <CheckboxIndicator>
        <span>✓</span>
    </CheckboxIndicator>
</CheckboxRoot>

With Label

Wrap the checkbox in a label for better accessibility and click handling.

razor
<label style="display: flex; gap: 0.5rem; align-items: center;">
    <CheckboxRoot id="c1">
        <CheckboxIndicator>
            <span>✓</span>
        </CheckboxIndicator>
    </CheckboxRoot>
    Accept terms and conditions
</label>

Controlled Mode

Control the checked state externally.

razor
@code {
    private bool isChecked = true;
}

<CheckboxRoot @bind-Checked="isChecked">
    <CheckboxIndicator>
        <span>✓</span>
    </CheckboxIndicator>
</CheckboxRoot>

Indeterminate State

Use the indeterminate state for parent checkboxes with partially selected children.

razor
@code {
    private bool isIndeterminate = true;
}

<CheckboxRoot @bind-Indeterminate="isIndeterminate">
    <CheckboxIndicator>
        @if (isIndeterminate)
        {
            <span>-</span>
        }
        else
        {
            <span>✓</span>
        }
    </CheckboxIndicator>
</CheckboxRoot>

Checkbox Group

Manage multiple checkboxes as a group.

razor
@code {
    private IReadOnlyList<string> values = new[] { "apple" };
}

<CheckboxGroup @bind-Values="values">
    <CheckboxGroupLabel>Favorite Fruits</CheckboxGroupLabel>
    
    <label>
        <CheckboxRoot Value="apple">
            <CheckboxIndicator>✓</CheckboxIndicator>
        </CheckboxRoot>
        Apple
    </label>
    
    <label>
        <CheckboxRoot Value="banana">
            <CheckboxIndicator>✓</CheckboxIndicator>
        </CheckboxRoot>
        Banana
    </label>
</CheckboxGroup>

Styling

Data Attributes

Attribute Values Description
data-state "checked" | "unchecked" | "indeterminate" Current state of the checkbox
data-disabled Present when disabled Indicates disabled state

CSS Example

css
/* Checkbox styles */
.checkbox {
    width: 1.25rem;
    height: 1.25rem;
    display: flex;
    align-items: center;
    justify-content: center;
    background: transparent;
    border: 2px solid #ccc;
    border-radius: 4px;
    cursor: pointer;
}

.checkbox:hover {
    border-color: #666;
}

.checkbox[data-state="checked"],
.checkbox[data-state="indeterminate"] {
    background: #0066cc;
    border-color: #0066cc;
}

.checkbox[data-disabled] {
    opacity: 0.5;
    cursor: not-allowed;
}

/* Indicator styles */
.checkbox-indicator {
    color: white;
}

Accessibility

Keyboard Navigation

Key Action
Space Toggles the checkbox state

ARIA Attributes

  • role: checkbox is set on the root element
  • aria-checked: Reflects the current state (true, false, or mixed)
  • aria-label: Provides an accessible name when set via the AriaLabel parameter
  • aria-disabled: Set when the checkbox is disabled
  • aria-required: Set when the checkbox is required
An unhandled error has occurred. Reload X