switch

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

Airplane Mode

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-preview',
  imports: [ZardSwitchComponent],
  template: `
    <z-switch zId="airplane-mode">Airplane Mode</z-switch>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchPreviewComponent {}

Installation

npx zard-cli@latest add switch

pnpm dlx zard-cli@latest add switch

yarn dlx zard-cli@latest add switch

bunx zard-cli@latest add switch

Add switch.component.ts

Create the following file in your project.

switch.component.ts

import {
  booleanAttribute,
  ChangeDetectionStrategy,
  Component,
  computed,
  forwardRef,
  input,
  model,
  signal,
  ViewEncapsulation,
} from '@angular/core';
import { type ControlValueAccessor, NG_VALUE_ACCESSOR } from '@angular/forms';

import type { ClassValue } from 'clsx';

import { ZardIdDirective } from '@/shared/core';
import { mergeClasses } from '@/shared/utils/merge-classes';
import { noopFn } from '@/shared/utils/noop';

import { switchVariants, type ZardSwitchSizeVariants } from './switch.variants';

type OnTouchedType = () => void;
type OnChangeType = (value: boolean) => void;

@Component({
  selector: 'z-switch',
  imports: [ZardIdDirective],
  template: `
    <span class="flex items-center space-x-2" zardId="switch" #z="zardId" [attr.data-checked]="zChecked() ? '' : null">
      <button
        [id]="zId() || z.id()"
        type="button"
        role="switch"
        [attr.data-state]="status()"
        [attr.aria-checked]="zChecked()"
        [attr.aria-invalid]="zInvalid() ? 'true' : null"
        [class]="classes()"
        [disabled]="zDisabled() || formDisabled()"
        (click)="onSwitchChange()"
      >
        <span
          [attr.data-size]="zSize()"
          [attr.data-state]="status()"
          class="bg-background dark:data-[state=checked]:bg-primary-foreground dark:data-[state=unchecked]:bg-foreground pointer-events-none block rounded-full ring-0 transition-transform data-[size=default]:size-4 data-[size=sm]:size-3 data-[state=unchecked]:translate-x-0 ltr:data-[state=checked]:translate-x-[calc(100%-2px)] rtl:data-[state=checked]:-translate-x-[calc(100%-2px)]"
        ></span>
      </button>

      <label
        class="text-sm leading-none font-medium peer-disabled:cursor-not-allowed peer-disabled:opacity-70"
        [for]="zId() || z.id()"
      >
        <ng-content><span class="sr-only">toggle switch</span></ng-content>
      </label>
    </span>
  `,
  providers: [
    {
      provide: NG_VALUE_ACCESSOR,
      useExisting: forwardRef(() => ZardSwitchComponent),
      multi: true,
    },
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  encapsulation: ViewEncapsulation.None,
  host: {
    'data-slot': 'switch',
  },
  exportAs: 'zSwitch',
})
export class ZardSwitchComponent implements ControlValueAccessor {
  readonly class = input<ClassValue>('');
  readonly zChecked = model<boolean>(false);
  readonly zId = input<string>('');
  readonly zSize = input<ZardSwitchSizeVariants>('default');
  readonly zDisabled = input(false, { transform: booleanAttribute });
  readonly zInvalid = input(false, { transform: booleanAttribute });

  private onChange: OnChangeType = noopFn;
  private onTouched: OnTouchedType = noopFn;

  protected readonly status = computed(() => (this.zChecked() ? 'checked' : 'unchecked'));
  protected readonly classes = computed(() => mergeClasses(switchVariants({ zSize: this.zSize() }), this.class()));

  protected readonly formDisabled = signal(false);

  writeValue(val: boolean): void {
    this.zChecked.set(val);
  }

  registerOnChange(fn: OnChangeType): void {
    this.onChange = fn;
  }

  registerOnTouched(fn: OnTouchedType): void {
    this.onTouched = fn;
  }

  onSwitchChange(): void {
    if (this.zDisabled() || this.formDisabled()) {
      return;
    }

    this.zChecked.update(checked => !checked);
    this.onTouched();
    this.onChange(this.zChecked());
  }

  setDisabledState(isDisabled: boolean): void {
    this.formDisabled.set(isDisabled);
  }
}

Add switch.variants.ts

Create the following file in your project.

switch.variants.ts

import { cva, type VariantProps } from 'class-variance-authority';

export const switchVariants = cva(
  'peer relative inline-flex shrink-0 cursor-pointer items-center rounded-full border border-transparent transition-all outline-none after:absolute after:-inset-x-3 after:-inset-y-2 focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40 data-[state=checked]:bg-primary data-[state=unchecked]:bg-input dark:data-[state=unchecked]:bg-input/80 disabled:cursor-not-allowed disabled:opacity-50',
  {
    variants: {
      zSize: {
        default: 'h-[18.4px] w-[32px]',
        sm: 'h-[14px] w-[24px]',
      },
    },
    defaultVariants: {
      zSize: 'default',
    },
  },
);

export type ZardSwitchSizeVariants = NonNullable<VariantProps<typeof switchVariants>['zSize']>;

Usage

import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

<z-switch></z-switch>

Examples

description

Pair z-field-content with z-field-label and z-field-description for helper text.

Share across devices

Focus is shared across devices, and turns off when you leave the app.

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-description',
  imports: [...ZardFieldImports, ZardSwitchComponent],
  template: `
    <div z-field zOrientation="horizontal" class="max-w-sm">
      <div z-field-content>
        <label z-field-label for="switch-focus-mode">Share across devices</label>
        <p z-field-description>Focus is shared across devices, and turns off when you leave the app.</p>
      </div>
      <z-switch zId="switch-focus-mode" />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchDescriptionComponent {}

choice card

Card-style selection where label[z-field-label] wraps the entire z-field for a clickable card pattern.

Share across devices

Focus is shared across devices, and turns off when you leave the app.

Enable notifications

Receive notifications when focus mode is enabled or disabled.

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-choice-card',
  imports: [...ZardFieldImports, ZardSwitchComponent],
  template: `
    <div z-field-group class="w-full min-w-sm">
      <label z-field-label for="switch-share">
        <div z-field zOrientation="horizontal">
          <div z-field-content>
            <div z-field-title>Share across devices</div>
            <p z-field-description>Focus is shared across devices, and turns off when you leave the app.</p>
          </div>
          <z-switch zId="switch-share"><span class="sr-only">Share across devices</span></z-switch>
        </div>
      </label>
      <label z-field-label for="switch-notifications">
        <div z-field zOrientation="horizontal">
          <div z-field-content>
            <div z-field-title>Enable notifications</div>
            <p z-field-description>Receive notifications when focus mode is enabled or disabled.</p>
          </div>
          <z-switch zId="switch-notifications" [zChecked]="true">
            <span class="sr-only">Enable notifications</span>
          </z-switch>
        </div>
      </label>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchChoiceCardComponent {}

disabled

Use zDisabled to disable the switch, and add data-disabled to z-field for the matching wrapper styles.

Disabled

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-disabled',
  imports: [...ZardFieldImports, ZardSwitchComponent],
  template: `
    <div z-field zOrientation="horizontal" data-disabled="true" class="w-fit">
      <z-switch zId="switch-disabled-unchecked" zDisabled />
      <label z-field-label for="switch-disabled-unchecked">Disabled</label>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchDisabledComponent {}

invalid

Use zInvalid to mark the switch as invalid (sets aria-invalid), and add data-invalid to z-field for the matching wrapper styles.

Accept terms and conditions

You must accept the terms and conditions to continue.

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-invalid',
  imports: [...ZardFieldImports, ZardSwitchComponent],
  template: `
    <div z-field zOrientation="horizontal" data-invalid="true" class="max-w-sm">
      <div z-field-content>
        <label z-field-label for="switch-terms">Accept terms and conditions</label>
        <p z-field-description>You must accept the terms and conditions to continue.</p>
      </div>
      <z-switch zId="switch-terms" zInvalid />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchInvalidComponent {}

size

Use zSize to change the size of the switch (default or sm).

Small

Small (checked)

Default

Default (checked)

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-size',
  imports: [ZardSwitchComponent],
  template: `
    <div class="grid w-full min-w-sm gap-6">
      <div class="flex items-center gap-6">
        <z-switch zSize="sm">Small</z-switch>
        <z-switch zSize="sm" [zChecked]="true">Small (checked)</z-switch>
      </div>
      <div class="flex items-center gap-6">
        <z-switch>Default</z-switch>
        <z-switch [zChecked]="true">Default (checked)</z-switch>
      </div>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchSizeComponent {}

controlled

Drive the switch from outside with a one-way [zChecked] binding and the (zCheckedChange) output, instead of the two-way [(zChecked)] binding.

Enable notifications

Notifications are on.

import { ChangeDetectionStrategy, Component, signal } from '@angular/core';

import { ZardButtonComponent } from '@/shared/components/button';
import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-controlled',
  imports: [ZardSwitchComponent, ZardButtonComponent, ...ZardFieldImports],
  template: `
    <div z-field-group class="mx-auto w-64">
      <div z-field zOrientation="horizontal">
        <z-switch
          zId="notifications-controlled"
          [zChecked]="notifications()"
          (zCheckedChange)="notifications.set($event)"
        />
        <label z-field-label for="notifications-controlled">Enable notifications</label>
      </div>
      <p class="text-muted-foreground text-sm">Notifications are {{ notifications() ? 'on' : 'off' }}.</p>
      <button type="button" z-button zType="outline" zSize="sm" (click)="notifications.set(!notifications())">
        Toggle from outside
      </button>
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchControlledComponent {
  protected readonly notifications = signal(true);
}

reactive forms

Bind z-switch with formControlName; a control created with disabled: true renders the switch disabled and keeps it in sync.

import { ChangeDetectionStrategy, Component, inject } from '@angular/core';
import { FormBuilder, ReactiveFormsModule } from '@angular/forms';

import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';

@Component({
  selector: 'z-demo-switch-reactive-forms',
  imports: [ZardSwitchComponent, ...ZardFieldImports, ReactiveFormsModule],
  template: `
    <form [formGroup]="form">
      <div z-field-group class="mx-auto w-64">
        <div z-field zOrientation="horizontal">
          <z-switch zId="newsletter-switch" formControlName="newsletter" />
          <label z-field-label for="newsletter-switch">Subscribe to newsletter</label>
        </div>
        <div z-field zOrientation="horizontal" data-disabled="true">
          <z-switch zId="beta-switch" formControlName="betaFeatures" />
          <label z-field-label for="beta-switch">Beta features (locked)</label>
        </div>
        <p class="text-muted-foreground text-sm">
          Newsletter: {{ form.controls.newsletter.value ? 'subscribed' : 'not subscribed' }}
        </p>
      </div>
    </form>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchReactiveFormsComponent {
  private readonly fb = inject(FormBuilder);

  protected readonly form = this.fb.group({
    newsletter: [true],
    betaFeatures: [{ value: false, disabled: true }],
  });
}

rtl

To enable RTL support in zard/ui, see the RTL configuration guide.

المشاركة عبر الأجهزة

تتم مشاركة التركيز عبر الأجهزة، ويتوقف عند مغادرة التطبيق.

// You will notice this example is rendered inside a wrapper that sets the dir and data-lang attributes, and
// reads its text from a translations helper. This is because this site is not RTL by default.
// In your application you won't need either: set dir="rtl" on <html> (or use the CDK Dir directive on a subtree)
// and write the text of your own language. See the RTL guide: https://zardui.com/docs/rtl

import { ChangeDetectionStrategy, Component } from '@angular/core';

import { ZardFieldImports } from '@/shared/components/field/field.imports';
import { ZardSwitchComponent } from '@/shared/components/switch/switch.component';
import { injectRtlTranslation, type ZardRtlTranslations } from '@/shared/demo-utils/rtl-translation';

const translations: ZardRtlTranslations<{ label: string; description: string }> = {
  en: {
    dir: 'ltr',
    values: {
      label: 'Share across devices',
      description: 'Focus is shared across devices, and turns off when you leave the app.',
    },
  },
  ar: {
    dir: 'rtl',
    values: {
      label: 'المشاركة عبر الأجهزة',
      description: 'تتم مشاركة التركيز عبر الأجهزة، ويتوقف عند مغادرة التطبيق.',
    },
  },
  he: {
    dir: 'rtl',
    values: {
      label: 'שיתוף בין מכשירים',
      description: 'המיקוד משותף בין מכשירים, ומתבטל כשעוזבים את האפליקציה.',
    },
  },
};

@Component({
  selector: 'z-demo-switch-rtl',
  imports: [...ZardFieldImports, ZardSwitchComponent],
  template: `
    <div z-field zOrientation="horizontal" class="max-w-sm">
      <div z-field-content>
        <label z-field-label for="switch-rtl">{{ i18n.t().label }}</label>
        <p z-field-description>{{ i18n.t().description }}</p>
      </div>
      <z-switch zId="switch-rtl" />
    </div>
  `,
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ZardDemoSwitchRtlComponent {
  protected readonly i18n = injectRtlTranslation(translations);
}

API Reference

z-switchComponent

A control that toggles between checked and unchecked, built on a native button with role="switch".

Property	Description	Type	Default
`[class]`	Additional CSS classes	`ClassValue`	`''`
`[zChecked]`	Checked state, two-way bindable	`boolean`	`false`
`[(zChecked)]`	Checked state (two-way binding)	`boolean`	`false`
`[zId]`	Id applied to the underlying button	`string`	`-`
`[zSize]`	Switch size	`'default' \| 'sm'`	`'default'`
`[zDisabled]`	Disables the switch	`boolean`	`false`
`[zInvalid]`	Invalid state (sets aria-invalid)	`boolean`	`false`