Docs

Main site

Installation Browser support Extend config MCP server
Validation Page speed testing Responsive design
Accordion Aspect Ratio Avatar Badge Banner Bento Grid Blockquote Breadcrumbs Button Callout Card Drawer Dropdown Link Modal Navbar Navblock Pagination Popover Progress Separator Tabs Timeline Toast Tooltip
Checkbox Datepicker File upload Form field Input Label OTP Radio Range Select Textarea Toggle
Header Footer
Accordion Auth Checkbox & Radio Content Drawers Features Modals Statistics & Metrics Teams Dropdowns
Address Contact number Currency symbol Date Emirates ID Name
Close
Home Documentation Components Toggle

Toggle

A Toggle is a switch input that lets users turn a single setting on or off. It is the right choice for binary preferences that take effect immediately — notification channels, language preference, accessibility options — and provides clear visual and assistive-technology feedback for the current state.

input Interactive
Status
Active
Introduced
4.0.x
View source code

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.

Image showing anatomy of a toggle

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>

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>

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>

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>

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>

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>

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>

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>

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>

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

AttributeDescriptionTypeDefault

field-id

DOM id for the underlying <input>. Auto-generated if omitted.

string

auto-generated

name

Form field name used during submission.

string

undefined

value

Form value submitted when the toggle is checked.

string

undefined

is-checked

Whether the toggle is on. Reflected to the host attribute as the user interacts, so the is-checked attribute, the isChecked property and the inner input's aria-checked always agree.

boolean

false

size

Size token or a responsive string.

xs | sm | base | lg | xl

base

variant

Colour family for the ON track and the focus ring (camel for primary, desert for secondary, seablue for the neutrals). The OFF track always stays aeblack-100 with a 2px aeblack-500 inner edge, and the error ring stays aered regardless of variant.

primary | secondary | neutral-max | neutral-min

primary

is-disabled

Disables the input and removes it from the tab order.

boolean

false

is-required

Marks the underlying input as required for form validation.

boolean

false

label

Inline label text rendered after the switch. Without it, the toggle renders as a bare switch — supply an accessible name another way (see Accessibility).

string

undefined

hint

Helper hint text shown below the label. Only rendered when label is set. It stays visible while an error shows — the error renders after it and both are announced as the description.

string

undefined

is-invalid

Puts the toggle into an error state and shows the error message.

boolean

false

error-message

Error text shown when is-invalid is true. Use the error slot for rich markup.

string

''

Slots

SlotDescription

icon-checked

Icon shown inside the thumb when the toggle is on. Keep it small (≤14×14px) and decorative — the state is already announced via aria-checked.

icon-unchecked

Icon shown inside the thumb when the toggle is off.

hint

Rich hint markup. Replaces the hint prop when provided.

error

Rich error markup. Replaces error-message when provided.

Events

EventDetailDescription

aegovToggleChange

{ checked: boolean; value?: string }

Fires after every state change with the new checked value.

aegovValidate

AegovValidationDetail<boolean>

Fires on change, blur, and after a programmatic validate() call. Detail includes name, value, validity, validationMessage, customError, and trigger.

Methods

MethodReturnsDescription

validate(trigger?)

Promise<AegovValidationResult>

Re-runs validation and emits aegovValidate. trigger is 'blur' | 'change' | 'manual' (default 'manual').

setCustomValidity(message)

Promise<void>

Sets a custom error message, mirroring HTMLInputElement.setCustomValidity(). Pass '' to clear it.

Pass-through attributes

Attribute groupForwarded?Notes

aria-*

Yes

Use to extend ARIA semantics, e.g. aria-labelledby for a bare switch labelled by external text.

data-*

Yes

Useful for analytics or test selectors.

form

Yes

Associates the input with a form by id when the toggle isn't nested inside it.

tabindex

Yes

Override the default tab order.

autofocus

Yes

Focus the toggle on initial page load.

title

Yes

Native browser tooltip text.

id

n/a

Not forwarded. Use field-id — it sets the real id of the inner input.

Notes

The following notes are applicable of this component.

Built-in accessibility

  • The control is a native <input type="checkbox"> with role="switch" and an explicit aria-checked state, so assistive technology announces "switch, on"/"switch, off" rather than "checkbox, checked".
  • When hint (or the hint slot) is provided, the input is linked to it via aria-describedby so 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-required sets both the native required attribute and aria-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 with is-invalid from the start shows the error text immediately but without role="alert", which appears only after the first blur.
  • When label is 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's checked state, and the isChecked JS 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 via aria-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-unchecked decorative — the state is already announced via aria-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.