ISA-Frontend/libs/ui/switch/README.md

UI Switch Library

This library provides a toggle switch component with an icon for Angular applications.

Components

IconSwitchComponent

A toggle switch component that displays an icon and supports two states (on/off).

Important: Use only when the icon meaning is universally clear, otherwise prefer a labeled switch.

Features

• ✅ Customizable icon via ng-icons
• ✅ Two-way binding with model signal
• ✅ Hover state styling
• ✅ Disabled state handling
• ✅ Keyboard navigation support (Enter, Space)
• ✅ Fully accessible with ARIA attributes
• ✅ Smooth animations

Usage

import { Component } from '@angular/core';
import { IconSwitchComponent } from '@isa/ui/switch';
import { provideIcons } from '@ng-icons/core';
import { isaNavigationDashboard } from '@isa/icons';

@Component({
  selector: 'app-example',
  standalone: true,
  imports: [IconSwitchComponent],
  providers: [provideIcons({ isaNavigationDashboard })],
  template: `
    <ui-icon-switch
      icon="isaNavigationDashboard"
      [(checked)]="isEnabled"
      [disabled]="false">
    </ui-icon-switch>
  `,
})
export class ExampleComponent {
  isEnabled = false;
}

Inputs

Property	Type	Default	Description
icon	string	(required)	The name of the icon to display
checked	boolean	false	Two-way bindable signal for the checked state
color	IconSwitchColor	'primary'	The color theme of the switch
disabled	boolean	false	Whether the switch is disabled
tabIndex	number	0	The tab index for keyboard navigation

Two-Way Binding

The checked property uses Angular's new model signal syntax for two-way binding:

<!-- Two-way binding -->
<ui-icon-switch icon="isaNavigationDashboard" [(checked)]="isEnabled"></ui-icon-switch>

<!-- One-way binding -->
<ui-icon-switch icon="isaNavigationDashboard" [checked]="isEnabled"></ui-icon-switch>

<!-- Event handling -->
<ui-icon-switch 
  icon="isaNavigationDashboard" 
  [checked]="isEnabled" 
  (checkedChange)="onToggle($event)">
</ui-icon-switch>

Accessibility

The component follows WAI-ARIA best practices:

• role="switch" - Identifies the element as a switch
• aria-checked - Indicates the current state
• aria-disabled - Indicates when the switch is disabled
• tabindex - Allows keyboard focus and navigation
• Keyboard support:
  • Enter - Toggles the switch
  • Space - Toggles the switch

Styling

The component uses the following CSS classes:

• .ui-icon-switch - Main component class
• .ui-icon-switch__primary - Primary color theme (currently the only supported theme)
• .ui-icon-switch__track - The pill-shaped background track
• .ui-icon-switch__track--checked - Applied when checked
• .ui-icon-switch__thumb - The circular toggle indicator with icon
• .ui-icon-switch__thumb--checked - Applied when checked
• .disabled - Applied when disabled

Color Themes

Currently, only the primary theme is supported, which uses:

• Unchecked: Neutral gray background (isa-neutral-300)
• Checked: Secondary blue background (isa-secondary-600)
• Hover (unchecked): Darker neutral gray (isa-neutral-400)
• Hover (checked): Darker secondary blue (isa-secondary-700)
• Thumb: White background with icon color matching the state

Examples

Basic usage:

<ui-icon-switch
  icon="isaNavigationDashboard"
  [(checked)]="dashboardEnabled">
</ui-icon-switch>

Disabled switch:

<ui-icon-switch
  icon="isaNavigationDashboard"
  [(checked)]="isEnabled"
  [disabled]="true">
</ui-icon-switch>

With event handling:

@Component({
  template: `
    <ui-icon-switch
      icon="isaNavigationDashboard"
      [(checked)]="isEnabled"
      (checkedChange)="handleToggle($event)">
    </ui-icon-switch>
  `,
})
export class ExampleComponent {
  isEnabled = false;

  handleToggle(checked: boolean): void {
    console.log('Switch toggled:', checked);
    // Perform action based on state
  }
}

Design Guidelines

When to use Icon Switch:

• ✅ The icon meaning is universally clear (e.g., home, dashboard, notification)
• ✅ Space is limited
• ✅ The action is binary (on/off, enabled/disabled)

When NOT to use Icon Switch:

• ❌ The icon meaning is ambiguous or context-specific
• ❌ Multiple related switches need differentiation
• ❌ Users need explicit labels for clarity

For cases where labels are needed, consider using a standard labeled switch component instead.

Development

Running unit tests

Run nx test ui-switch to execute the unit tests with Vitest.

Running Storybook

The component has a Storybook story at apps/isa-app/stories/ui/switch/ui-icon-switch.stories.ts.

Run Storybook to see the component in action:

npm run storybook