Anatomy
A toggle is a native checkbox with role="switch", rendered as a rounded track and a circular thumb that slides between OFF and ON. An optional label and hint sit to the side; an optional error message appears below them when the toggle is invalid, with the hint still visible.

| Item | Name | Description |
|---|---|---|
1 |
Track | The rounded background. Grey when off; coloured by variant when on. |
2 |
Thumb | The circle that slides across the track. Can host an icon-checked/icon-unchecked slot. |
3 |
Label | Optional inline text from the label prop, rendered after the switch. Wraps the whole row in a <label> when present. |
4 |
Hint | Optional helper text below the label — stays visible while an error shows. |
5 |
Error message | Shown after the hint when is-invalid="true". |
Basics
aegov-toggle renders a fully accessible switch on a native <input type="checkbox"> with role="switch". Supply label for an inline label and hint for supporting text below it — the label text becomes clickable along with the switch.
<aegov-toggle
field-id="toggle-basics"
label="Enable SMS notifications"
hint="Receive transactional updates on your registered UAE mobile number."
is-checked="true"
></aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleBasics() {
return (
<AegovToggle
fieldId="toggle-basics"
label="Enable SMS notifications"
hint="Receive transactional updates on your registered UAE mobile number."
isChecked
/>
);
}
<template>
<aegov-toggle
field-id="toggle-basics"
label="Enable SMS notifications"
hint="Receive transactional updates on your registered UAE mobile number."
is-checked="true"
></aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-basics',
imports: [AegovToggle],
template: `
<aegov-toggle
field-id="toggle-basics"
label="Enable SMS notifications"
hint="Receive transactional updates on your registered UAE mobile number."
[isChecked]="true"
></aegov-toggle>
`,
})
export class ToggleBasicsComponent {}
Sizes
size scales the track, thumb, and label/hint typography together. Five tokens are available — xs, sm, base (default), lg, and xl — and, like Badge and Callout, it accepts a responsive breakpoint string such as size="sm md:base xl:lg".
<aegov-toggle field-id="toggle-size-xs" size="xs" label="Extra small"></aegov-toggle>
<aegov-toggle field-id="toggle-size-sm" size="sm" label="Small"></aegov-toggle>
<aegov-toggle field-id="toggle-size-base" size="base" label="Base (default)"></aegov-toggle>
<aegov-toggle field-id="toggle-size-lg" size="lg" label="Large"></aegov-toggle>
<aegov-toggle field-id="toggle-size-xl" size="xl" label="Extra large"></aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleSizes() {
return (
<>
<AegovToggle fieldId="toggle-size-xs" size="xs" label="Extra small" />
<AegovToggle fieldId="toggle-size-sm" size="sm" label="Small" />
<AegovToggle fieldId="toggle-size-base" size="base" label="Base (default)" />
<AegovToggle fieldId="toggle-size-lg" size="lg" label="Large" />
<AegovToggle fieldId="toggle-size-xl" size="xl" label="Extra large" />
</>
);
}
<template>
<aegov-toggle field-id="toggle-size-xs" size="xs" label="Extra small"></aegov-toggle>
<aegov-toggle field-id="toggle-size-sm" size="sm" label="Small"></aegov-toggle>
<aegov-toggle field-id="toggle-size-base" size="base" label="Base (default)"></aegov-toggle>
<aegov-toggle field-id="toggle-size-lg" size="lg" label="Large"></aegov-toggle>
<aegov-toggle field-id="toggle-size-xl" size="xl" label="Extra large"></aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-sizes',
imports: [AegovToggle],
template: `
<aegov-toggle field-id="toggle-size-xs" size="xs" label="Extra small"></aegov-toggle>
<aegov-toggle field-id="toggle-size-sm" size="sm" label="Small"></aegov-toggle>
<aegov-toggle field-id="toggle-size-base" size="base" label="Base (default)"></aegov-toggle>
<aegov-toggle field-id="toggle-size-lg" size="lg" label="Large"></aegov-toggle>
<aegov-toggle field-id="toggle-size-xl" size="xl" label="Extra large"></aegov-toggle>
`,
})
export class ToggleSizesComponent {}
Variant
variant selects the colour family of the ON track, the focus ring, and a thumb icon in the ON state. The OFF track always stays aeblack-100 with a 2px aeblack-500 inner edge (so the switch keeps 3:1 contrast against the page), and the thumb stays white with a 2px aeblack-500 border regardless of variant.
| Variant | OFF track | ON track |
|---|---|---|
primary (default) |
aeblack-100 |
primary-600 |
secondary |
aeblack-100 |
secondary-600 |
neutral-max |
aeblack-100 |
aeblack-800 |
neutral-min |
aeblack-100 |
aeblack-400 |
<aegov-toggle field-id="toggle-variant-primary" variant="primary" label="Primary" is-checked="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-secondary" variant="secondary" label="Secondary" is-checked="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-neutral-max" variant="neutral-max" label="Neutral max" is-checked="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-neutral-min" variant="neutral-min" label="Neutral min" is-checked="true"></aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleVariant() {
return (
<>
<AegovToggle fieldId="toggle-variant-primary" variant="primary" label="Primary" isChecked />
<AegovToggle fieldId="toggle-variant-secondary" variant="secondary" label="Secondary" isChecked />
<AegovToggle fieldId="toggle-variant-neutral-max" variant="neutral-max" label="Neutral max" isChecked />
<AegovToggle fieldId="toggle-variant-neutral-min" variant="neutral-min" label="Neutral min" isChecked />
</>
);
}
<template>
<aegov-toggle field-id="toggle-variant-primary" variant="primary" label="Primary" is-checked="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-secondary" variant="secondary" label="Secondary" is-checked="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-neutral-max" variant="neutral-max" label="Neutral max" is-checked="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-neutral-min" variant="neutral-min" label="Neutral min" is-checked="true"></aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-variant',
imports: [AegovToggle],
template: `
<aegov-toggle field-id="toggle-variant-primary" variant="primary" label="Primary" [isChecked]="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-secondary" variant="secondary" label="Secondary" [isChecked]="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-neutral-max" variant="neutral-max" label="Neutral max" [isChecked]="true"></aegov-toggle>
<aegov-toggle field-id="toggle-variant-neutral-min" variant="neutral-min" label="Neutral min" [isChecked]="true"></aegov-toggle>
`,
})
export class ToggleVariantComponent {}
Checked and unchecked states
Use is-checked to set the initial state. As the user switches the toggle, the host is-checked attribute, the isChecked JS property and the inner input's aria-checked/checked stay in sync — read whichever suits you, or listen for aegovToggleChange.
<aegov-toggle field-id="toggle-off" label="Off by default"></aegov-toggle>
<aegov-toggle field-id="toggle-on" label="On by default" is-checked="true"></aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleStates() {
return (
<>
<AegovToggle fieldId="toggle-off" label="Off by default" />
<AegovToggle fieldId="toggle-on" label="On by default" isChecked />
</>
);
}
<template>
<aegov-toggle field-id="toggle-off" label="Off by default"></aegov-toggle>
<aegov-toggle field-id="toggle-on" label="On by default" is-checked="true"></aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-states',
imports: [AegovToggle],
template: `
<aegov-toggle field-id="toggle-off" label="Off by default"></aegov-toggle>
<aegov-toggle field-id="toggle-on" label="On by default" [isChecked]="true"></aegov-toggle>
`,
})
export class ToggleStatesComponent {}
Disabled
Set is-disabled="true" to prevent interaction. The track and thumb are visually muted, and the underlying input receives the native disabled attribute — removing it from the tab order and from form submission.
<aegov-toggle field-id="toggle-disabled-off" label="Disabled (off)" is-disabled="true"></aegov-toggle>
<aegov-toggle field-id="toggle-disabled-on" label="Disabled (on)" is-disabled="true" is-checked="true"></aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleDisabled() {
return (
<>
<AegovToggle fieldId="toggle-disabled-off" label="Disabled (off)" isDisabled />
<AegovToggle fieldId="toggle-disabled-on" label="Disabled (on)" isDisabled isChecked />
</>
);
}
<template>
<aegov-toggle field-id="toggle-disabled-off" label="Disabled (off)" is-disabled="true"></aegov-toggle>
<aegov-toggle field-id="toggle-disabled-on" label="Disabled (on)" is-disabled="true" is-checked="true"></aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-disabled',
imports: [AegovToggle],
template: `
<aegov-toggle field-id="toggle-disabled-off" label="Disabled (off)" [isDisabled]="true"></aegov-toggle>
<aegov-toggle field-id="toggle-disabled-on" label="Disabled (on)" [isDisabled]="true" [isChecked]="true"></aegov-toggle>
`,
})
export class ToggleDisabledComponent {}
Custom on/off icons
Use the icon-checked and icon-unchecked slots to swap a small glyph inside the thumb as the toggle changes state. Keep icons small and purely decorative — the state is already announced through aria-checked.
<aegov-toggle field-id="toggle-icons" label="Dark mode" size="lg">
<svg slot="icon-checked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
</svg>
<svg slot="icon-unchecked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
<circle cx="12" cy="12" r="5"/>
</svg>
</aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleIcons() {
return (
<AegovToggle fieldId="toggle-icons" label="Dark mode" size="lg">
<svg slot="icon-checked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2.5} strokeLinecap="round" strokeLinejoin="round">
<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z" />
</svg>
<svg slot="icon-unchecked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth={2.5} strokeLinecap="round" strokeLinejoin="round">
<circle cx="12" cy="12" r="5" />
</svg>
</AegovToggle>
);
}
<template>
<aegov-toggle field-id="toggle-icons" label="Dark mode" size="lg">
<svg slot="icon-checked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
</svg>
<svg slot="icon-unchecked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
<circle cx="12" cy="12" r="5"/>
</svg>
</aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-icons',
imports: [AegovToggle],
template: `
<aegov-toggle field-id="toggle-icons" label="Dark mode" size="lg">
<svg slot="icon-checked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
<path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
</svg>
<svg slot="icon-unchecked" xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round">
<circle cx="12" cy="12" r="5"/>
</svg>
</aegov-toggle>
`,
})
export class ToggleIconsComponent {}
Invalid (error state)
Set is-invalid="true" with error-message to show a validation error below the label — the hint stays visible, because it often says how to fix the error. The error region only takes role="alert" after the user has blurred the field at least once, so a validation message present at initial load isn't announced as an interruption.
<aegov-toggle
field-id="toggle-invalid"
name="consent"
label="I consent to receive service updates by email"
is-invalid="true"
error-message="You must accept to continue"
></aegov-toggle>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleInvalid() {
return (
<AegovToggle
fieldId="toggle-invalid"
name="consent"
label="I consent to receive service updates by email"
isInvalid
errorMessage="You must accept to continue"
/>
);
}
<template>
<aegov-toggle
field-id="toggle-invalid"
name="consent"
label="I consent to receive service updates by email"
is-invalid="true"
error-message="You must accept to continue"
></aegov-toggle>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-invalid',
imports: [AegovToggle],
template: `
<aegov-toggle
field-id="toggle-invalid"
name="consent"
label="I consent to receive service updates by email"
[isInvalid]="true"
error-message="You must accept to continue"
></aegov-toggle>
`,
})
export class ToggleInvalidComponent {}
Form integration
Provide name and value to participate in standard form submission. When checked, the payload includes the given value under that name; when unchecked, the field is omitted entirely — matching native checkbox behaviour. Add is-required="true" to mark it required for form validation.
<form>
<aegov-toggle
field-id="toggle-form"
name="marketing_consent"
value="yes"
label="I consent to receive service updates by email"
is-required="true"
></aegov-toggle>
</form>
import { AegovToggle } from '@aegov/designsystem-react';
export default function ToggleForm() {
return (
<form>
<AegovToggle
fieldId="toggle-form"
name="marketing_consent"
value="yes"
label="I consent to receive service updates by email"
isRequired
/>
</form>
);
}
<template>
<form>
<aegov-toggle
field-id="toggle-form"
name="marketing_consent"
value="yes"
label="I consent to receive service updates by email"
is-required="true"
></aegov-toggle>
</form>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-toggle-form',
imports: [AegovToggle],
template: `
<form>
<aegov-toggle
field-id="toggle-form"
name="marketing_consent"
value="yes"
label="I consent to receive service updates by email"
[isRequired]="true"
></aegov-toggle>
</form>
`,
})
export class ToggleFormComponent {}
RTL support
The toggle is direction-agnostic. When the document or any ancestor is set to dir="rtl", the label moves to the inline-end automatically and the thumb travels in the mirrored direction when checked.
<div dir="rtl">
<aegov-toggle
field-id="toggle-rtl"
label="تفعيل الإشعارات عبر الرسائل النصية"
hint="استلام تحديثات الخدمة على رقم هاتفك المتحرك المسجل في دولة الإمارات."
is-checked="true"
></aegov-toggle>
</div>
import { AegovToggle } from '@aegov/designsystem-react';
export default function RtlToggle() {
return (
<div dir="rtl">
<AegovToggle
fieldId="toggle-rtl"
label="تفعيل الإشعارات عبر الرسائل النصية"
hint="استلام تحديثات الخدمة على رقم هاتفك المتحرك المسجل في دولة الإمارات."
isChecked
/>
</div>
);
}
<template>
<div dir="rtl">
<aegov-toggle
field-id="toggle-rtl"
label="تفعيل الإشعارات عبر الرسائل النصية"
hint="استلام تحديثات الخدمة على رقم هاتفك المتحرك المسجل في دولة الإمارات."
is-checked="true"
></aegov-toggle>
</div>
</template>
import { Component } from '@angular/core';
import { AegovToggle } from '@aegov/designsystem-angular';
@Component({
selector: 'app-rtl-toggle',
imports: [AegovToggle],
template: `
<div dir="rtl">
<aegov-toggle
field-id="toggle-rtl"
label="تفعيل الإشعارات عبر الرسائل النصية"
hint="استلام تحديثات الخدمة على رقم هاتفك المتحرك المسجل في دولة الإمارات."
[isChecked]="true"
></aegov-toggle>
</div>
`,
})
export class RtlToggleComponent {}
Usage
Here is the recommended usage of a toggle on any website or application. These are recommended usage guides, however the developer must use the best practices of web and application development to accurately use this component.
Use a toggle only for settings that take effect immediately
Notification channels, language, accessibility preferences — anything applied the moment the user flips it. For a choice that only applies after a Save action, use a checkbox instead.
Always give the toggle an accessible name
Supply label, or when it must render as a bare switch, link an external <aegov-label>/visible text via aria-labelledby. A switch with no accessible name is opaque to screen reader users.
Keep on/off icons decorative
The state is already announced through aria-checked ("switch, on"/"switch, off"). Don't encode information in the icon that isn't also in the label or hint.
Provide name and value for any toggle inside a form
On submit the value is included only when checked, matching native checkbox behaviour — omit them for a toggle that only drives client-side UI state.
Don't use a toggle for an action that needs explicit confirmation
A destructive or hard-to-reverse change (e.g. deleting an account) belongs behind a button and a confirmation dialog, not a switch that fires immediately on interaction.
Don't rely on the icon slots alone to convey meaning
icon-checked/icon-unchecked sit inside a small circular thumb and are easy to misread at a glance — always pair the toggle with a label or adjacent text.
API reference
The following are the properties and references of a toggle
aegov-toggle properties
| Attribute | Description | Type | Default |
|---|---|---|---|
| DOM |
| auto-generated |
| Form field name used during submission. |
|
|
| Form value submitted when the toggle is checked. |
|
|
| Whether the toggle is on. Reflected to the host attribute as the user interacts, so the |
|
|
| Size token or a responsive string. |
|
|
| Colour family for the ON track and the focus ring (camel for |
|
|
| Disables the input and removes it from the tab order. |
|
|
| Marks the underlying input as required for form validation. |
|
|
| Inline label text rendered after the switch. Without it, the toggle renders as a bare switch — supply an accessible name another way (see Accessibility). |
|
|
| Helper hint text shown below the label. Only rendered when |
|
|
| Puts the toggle into an error state and shows the error message. |
|
|
| Error text shown when |
|
|
Slots
| Slot | Description |
|---|---|
| Icon shown inside the thumb when the toggle is on. Keep it small (≤14×14px) and decorative — the state is already announced via |
| Icon shown inside the thumb when the toggle is off. |
| Rich hint markup. Replaces the |
| Rich error markup. Replaces |
Events
| Event | Detail | Description |
|---|---|---|
|
| Fires after every state change with the new checked value. |
|
| Fires on change, blur, and after a programmatic |
Methods
| Method | Returns | Description |
|---|---|---|
|
| Re-runs validation and emits |
|
| Sets a custom error message, mirroring |
Pass-through attributes
| Attribute group | Forwarded? | Notes |
|---|---|---|
| Yes | Use to extend ARIA semantics, e.g. |
| Yes | Useful for analytics or test selectors. |
| Yes | Associates the input with a form by |
| Yes | Override the default tab order. |
| Yes | Focus the toggle on initial page load. |
| Yes | Native browser tooltip text. |
| n/a | Not forwarded. Use |
Notes
The following notes are applicable of this component.
Built-in accessibility
- The control is a native
<input type="checkbox">withrole="switch"and an explicitaria-checkedstate, so assistive technology announces "switch, on"/"switch, off" rather than "checkbox, checked". - When
hint(or thehintslot) is provided, the input is linked to it viaaria-describedbyso screen readers read the helper text after the label. The same applies to the error message when shown — the hint stays visible alongside the error, and the description reads the error, then the hint. is-requiredsets both the nativerequiredattribute andaria-required="true".- The error region only takes
role="alert"after the user has blurred the field at least once, so a validation message present at initial load isn't announced as an interruption — confirmed live: a toggle rendered withis-invalidfrom the start shows the error text immediately but withoutrole="alert", which appears only after the first blur. - When
labelis supplied, the switch and its text are wrapped in a<label>, so clicking the label text — not just the switch itself — toggles the control. The clickable area is at least 24px tall at every size. aria-checked, the inner input'scheckedstate, and theisCheckedJS property always stay correct and in sync on every interaction — confirmed live across repeated toggling.
Developer responsibilities
- Always provide
label, or when the toggle must render as a bare switch, link an external label viaaria-labelledby. A switch without an accessible name is opaque to screen reader users. - Use a toggle only for settings that take effect immediately. For "save later" choices, use a checkbox.
- Keep
icon-checked/icon-uncheckeddecorative — the state is already announced viaaria-checked. Don't encode the toggle's only meaning in the icon.
Keyboard support
| Key | Action |
|---|---|
Space |
Toggle the switch on or off. |
Tab |
Move focus to the next focusable element. |
Shift + Tab |
Move focus to the previous focusable element. |