Checkbox Component ☑️

Interactive checkbox control with support for checked, unchecked, and indeterminate states, multiple variants, and full form integration.

Features

✅ 3 States - Checked, Unchecked, and Indeterminate support
🎯 4 Variants - Default, Destructive, Success, Warning
📏 4 Sizes - Small, Default, Large, Extra Large
♿ Accessibility - Full ARIA compliance and keyboard navigation
📝 Form Integration - ControlValueAccessor for reactive forms
🎨 Customizable - Easy styling with Tailwind CSS
🔧 TypeScript - Complete type safety and IntelliSense

Installation

Initialize Angular SuperUI in your project:

ngsui-cli init

Add the Checkbox component:

ngsui-cli add checkbox

Usage

Import the Checkbox component in your Angular component:

import { Component } from '@angular/core';
import { CheckboxComponent } from 'angular-superui';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [CheckboxComponent],
  template: `
    <div class="flex items-center space-x-2">
      <Checkbox [(ngModel)]="isChecked" />
      <label class="text-sm font-medium">Accept terms and conditions</label>
    </div>
  `
})
export class ExampleComponent {
  isChecked = false;
}

Examples

Basic Checkbox

<div class="flex items-center space-x-2">
  <Checkbox [(ngModel)]="isChecked" />
  <label class="text-sm font-medium">Accept terms and conditions</label>
</div>

Checkbox Sizes

<div class="space-y-3">
  <div class="flex items-center space-x-2">
    <Checkbox size="sm" [(ngModel)]="smallCheckbox" />
    <label class="text-sm">Small checkbox</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox size="default" [(ngModel)]="defaultCheckbox" />
    <label class="text-sm">Default checkbox</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox size="lg" [(ngModel)]="largeCheckbox" />
    <label class="text-sm">Large checkbox</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox size="xl" [(ngModel)]="extraLargeCheckbox" />
    <label class="text-sm">Extra large checkbox</label>
  </div>
</div>

Checkbox Variants

<div class="space-y-3">
  <div class="flex items-center space-x-2">
    <Checkbox variant="default" [(ngModel)]="defaultVariant" />
    <label class="text-sm">Default variant</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox variant="destructive" [(ngModel)]="destructiveVariant" />
    <label class="text-sm">Destructive variant</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox variant="success" [(ngModel)]="successVariant" />
    <label class="text-sm">Success variant</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox variant="warning" [(ngModel)]="warningVariant" />
    <label class="text-sm">Warning variant</label>
  </div>
</div>

Checkbox States

<div class="space-y-3">
  <div class="flex items-center space-x-2">
    <Checkbox [(ngModel)]="uncheckedState" />
    <label class="text-sm">Unchecked state</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox [(ngModel)]="checkedState" />
    <label class="text-sm">Checked state</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox [indeterminate]="true" />
    <label class="text-sm">Indeterminate state</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox [disabled]="true" [(ngModel)]="disabledUnchecked" />
    <label class="text-sm text-gray-500">Disabled unchecked</label>
  </div>
  <div class="flex items-center space-x-2">
    <Checkbox [disabled]="true" [(ngModel)]="disabledChecked" />
    <label class="text-sm text-gray-500">Disabled checked</label>
  </div>
</div>

Checkbox with Accessibility

<div class="flex items-center space-x-2">
  <Checkbox 
    [(ngModel)]="newsletterSubscription" 
    [accessibility]="{
      ariaLabel: 'Subscribe to newsletter',
      ariaDescription: 'You can unsubscribe at any time',
      ariaRequired: true
    }" />
  <label class="text-sm">Subscribe to newsletter (required)</label>
</div>

Checkbox with Form Validation

<form [formGroup]="checkboxForm">
  <div class="flex items-center space-x-2">
    <Checkbox 
      formControlName="termsAccepted"
      [accessibility]="{
        ariaRequired: true,
        ariaInvalid: checkboxForm.get('termsAccepted')?.invalid && checkboxForm.get('termsAccepted')?.touched
      }" />
    <label class="text-sm">I accept the terms and conditions *</label>
  </div>
  <div class="text-sm text-red-600 mt-1" *ngIf="checkboxForm.get('termsAccepted')?.invalid && checkboxForm.get('termsAccepted')?.touched">
    Please accept the terms and conditions
  </div>
</form>

import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class ExampleComponent {
  checkboxForm: FormGroup;

  constructor(private fb: FormBuilder) {
    this.checkboxForm = this.fb.group({
      termsAccepted: [false, Validators.requiredTrue]
    });
  }
}

Checkbox with Custom Events

<div class="flex items-center space-x-2">
  <Checkbox 
    [(ngModel)]="customCheckbox"
    (checkedChange)="onCheckedChange($event)"
    (stateChange)="onStateChange($event)"
    (focused)="onFocus()"
    (blurred)="onBlur()" />
  <label class="text-sm">Custom event handling</label>
</div>

export class ExampleComponent {
  customCheckbox = false;

  onCheckedChange(checked: boolean) {
    console.log('Checkbox checked:', checked);
  }

  onStateChange(state: 'checked' | 'unchecked' | 'indeterminate') {
    console.log('Checkbox state:', state);
  }

  onFocus() {
    console.log('Checkbox focused');
  }

  onBlur() {
    console.log('Checkbox blurred');
  }
}

API Reference

Properties

Property	Type	Default	Description
`variant`	`'default' \| 'destructive' \| 'success' \| 'warning'`	`'default'`	Visual variant of the checkbox
`size`	`'sm' \| 'default' \| 'lg' \| 'xl'`	`'default'`	Size variant of the checkbox
`disabled`	`boolean`	`false`	Whether the checkbox is disabled
`indeterminate`	`boolean`	`false`	Whether the checkbox is in indeterminate state
`accessibility`	`CheckboxAccessibility`	`{}`	Accessibility configuration object
`class`	`string`	`''`	Additional CSS classes to apply

Events

Event	Type	Description
`checkedChange`	`EventEmitter<boolean>`	Emitted when the checkbox state changes
`stateChange`	`EventEmitter<CheckboxState>`	Emitted when the checkbox state changes (including indeterminate)
`focused`	`EventEmitter<void>`	Emitted when the checkbox is focused
`blurred`	`EventEmitter<void>`	Emitted when the checkbox loses focus

Types

CheckboxAccessibility

interface CheckboxAccessibility {
  ariaLabel?: string;           // ARIA label for screen readers
  ariaDescription?: string;     // ARIA description for additional context
  ariaLabelledBy?: string;      // Element ID that labels this checkbox
  ariaDescribedBy?: string;     // Element ID that describes this checkbox
  ariaRequired?: boolean;       // Indicates if the checkbox is required
  ariaInvalid?: boolean;        // Indicates if the checkbox is invalid
}

CheckboxState

type CheckboxState = 'checked' | 'unchecked' | 'indeterminate';

Methods

Method	Parameters	Return Type	Description
`setChecked`	`checked: boolean`	`void`	Programmatically set the checked state
`toggle`	-	`void`	Toggle the checkbox state
`setIndeterminate`	`indeterminate: boolean`	`void`	Set the indeterminate state
`checked`	-	`boolean`	Get the current checked state

Styling

The Checkbox component uses Tailwind CSS classes and CSS custom properties for styling. You can customize the appearance by:

Using Variants

<Checkbox variant="success" [(ngModel)]="value" />
<Checkbox variant="destructive" [(ngModel)]="value" />
<Checkbox variant="warning" [(ngModel)]="value" />

Using Custom Classes

<Checkbox class="ring-2 ring-blue-500" [(ngModel)]="value" />

CSS Custom Properties

The component respects the following CSS custom properties:

--primary: Primary color for default state
--primary-foreground: Foreground color for primary state
--destructive: Color for destructive variant
--destructive-foreground: Foreground color for destructive variant
--success: Color for success variant
--success-foreground: Foreground color for success variant
--warning: Color for warning variant
--warning-foreground: Foreground color for warning variant
--ring: Focus ring color
--border: Border color

Accessibility

The Checkbox component is fully accessible and follows WAI-ARIA guidelines:

Screen Reader Support

Uses proper role="checkbox" attribute
Provides aria-checked with appropriate values (true, false, mixed)
Supports aria-label, aria-labelledby, and aria-describedby
Indicates required and invalid states with aria-required and aria-invalid

Keyboard Navigation

Space/Enter: Toggle the checkbox state
Tab: Navigate to/from the checkbox
Shift+Tab: Navigate backwards

Focus Management

Visible focus indicator with customizable focus ring
Proper focus/blur event handling
Disabled state removes from tab order

Best Practices

Always provide labels: Use either visible labels or aria-label
Use proper form associations: Associate checkboxes with labels using for attribute or wrapping
Indicate required fields: Use aria-required and visual indicators
Provide error messages: Use aria-invalid and aria-describedby for validation errors
Use indeterminate state appropriately: For parent checkboxes controlling multiple child checkboxes

Form Integration

The Checkbox component implements Angular's ControlValueAccessor interface, making it fully compatible with Angular Forms:

Template-driven Forms

<form #form="ngForm">
  <div class="flex items-center space-x-2">
    <Checkbox [(ngModel)]="agreeToTerms" name="agreeToTerms" required />
    <label class="text-sm">I agree to the terms and conditions</label>
  </div>
</form>

Reactive Forms

import { FormBuilder, FormGroup, Validators } from '@angular/forms';

export class ExampleComponent {
  form: FormGroup;

  constructor(private fb: FormBuilder) {
    this.form = this.fb.group({
      agreeToTerms: [false, Validators.requiredTrue],
      newsletter: [false],
      updates: [false]
    });
  }
}

<form [formGroup]="form">
  <div class="space-y-3">
    <div class="flex items-center space-x-2">
      <Checkbox formControlName="agreeToTerms" />
      <label class="text-sm">I agree to the terms and conditions</label>
    </div>
    <div class="flex items-center space-x-2">
      <Checkbox formControlName="newsletter" />
      <label class="text-sm">Subscribe to newsletter</label>
    </div>
    <div class="flex items-center space-x-2">
      <Checkbox formControlName="updates" />
      <label class="text-sm">Receive product updates</label>
    </div>
  </div>
</form>

Design System Integration

The Checkbox component integrates seamlessly with design systems:

Tailwind CSS

Uses Tailwind utility classes for consistent spacing, colors, and typography.

CSS Custom Properties

Respects CSS custom properties for theme customization.

Design Tokens

Follows design token conventions for colors, spacing, and typography.

Performance

The Checkbox component is optimized for performance:

Signal-based architecture: Uses Angular 20 signals for fine-grained reactivity
Computed properties: Reactive updates only when dependencies change
Minimal re-renders: Efficient change detection with signals
Tree-shakeable: Only includes necessary code in your bundle

Browser Support

The Checkbox component supports all modern browsers:

Chrome 90+
Firefox 88+
Safari 14+
Edge 90+

Contributing

Found a bug or want to contribute? Please see our Contributing Guide.

License

This component is part of Angular SuperUI and is licensed under the MIT License.

FilesExpand file tree

checkbox.md

Latest commit

History

checkbox.md

File metadata and controls

Checkbox Component ☑️

Features

Installation

Usage

Examples

Basic Checkbox

Checkbox Sizes

Checkbox Variants

Checkbox States

Checkbox with Accessibility

Checkbox with Form Validation

Checkbox with Custom Events

API Reference

Properties

Events

Types

CheckboxAccessibility

CheckboxState

Methods

Styling

Using Variants

Using Custom Classes

CSS Custom Properties

Accessibility

Screen Reader Support

Keyboard Navigation

Focus Management

Best Practices

Form Integration

Template-driven Forms

Reactive Forms

Design System Integration

Tailwind CSS

CSS Custom Properties

Design Tokens

Performance

Browser Support

Contributing

License