Fields & selection

Toggle

A controlled switch for an immediate on/off setting.

ToggleToggleProps

Component workbench

Configure the production component, inspect it at responsive widths, copy synchronized JSX, and share the exact state from one workspace.

Generated example

This JSX stays synchronized with the controls and uses only public package APIs.

tsx

'use client';

import { useState } from 'react';
import { Toggle } from '@ai-created/ui';

export function Example() {
  const [checked, setChecked] = useState(false);

  return (
    <Toggle
      checked={checked}
      onChange={setChecked}
      label={"Enable notifications"}
    />
  );
}

Import

tsx

import { Toggle } from '@ai-created/ui';

Install from a reviewed release

Replace the version placeholder with the release tag your product has reviewed.

shell

npm install --install-links "git+https://github.com/TheMarco/ai-created-ui.git#vX.Y.Z"

Load semantic tokens

css

@import '@ai-created/ui/styles/tokens.css';

@tailwind base;
@tailwind components;
@tailwind utilities;

Extend Tailwind

module.exports = {
  presets: [require('@ai-created/ui/tailwind-preset')],
  content: [
    './src/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@ai-created/ui/src/**/*.{js,ts,jsx,tsx}',
  ],
};

Anatomy

Named regions define what belongs to the component, what remains optional, and where semantic responsibility lives.

Switch button

Required

44px-minimum interactive root.

button[role=switch]

Track

Required

40 × 24px visual state container and focus proxy.

Thumb

Required

16px moving state marker.

Label

Required

Visible switch name.

Construction and authoring

The Figma-equivalent asset model, auto-layout, resizing, properties, slots, content bounds, localization, and governance contract.

Asset kind

component

Design library name

Components/Forms/Toggle

Maturity

stable

Last reviewed

2026-08-29

Canvas applicability

Publish on, off, disabled, hover, focus, and pressed states with a label property.

Auto layout

Direction: horizontal
Gap: 10px
Padding: 0px
Alignment: Center vertically
Wrap: Label wraps

Resizing

Width: hug
Height: hug
Minimum width: 44px
Maximum width: Parent controlled
Minimum height: 44px
Maximum height: Content controlled
Overflow: visible

Exposed design properties

Property	Type	Default	Code mapping	Options or notes
OnRequired	boolean	false	checked	No additional constraint
Disabled	boolean	false	disabled	No additional constraint
LabelRequired	text	Enable notifications	label	No additional constraint

Nested assets and slots

Switch button

primitive / required

Native button with switch semantics.

<button role="switch">

Track

subcomponent / required

40px by 24px state surface.

Internal span

Thumb

subcomponent / required

16px moving state indicator.

Internal span

Label

slot / required

Setting name.

label

Content limits

Label

Short setting phrase, maximum two lines

Overflow: Wrap; never truncate.

The on and off consequence must be clear from the label and context.

Localization and RTL

Translatable: Label

Track remains visually consistent; label follows logical order.
Do not reverse the semantic meaning of the checked state.
Test a two-line label.
Verify switch announcement in localized screen-reader output.

Responsive behavior

Intrinsic control within a parent settings row.

No internal breakpoint

Parent may place explanatory copy below.
Maintain a 44px minimum target.

Authoring limits

Prototype motion does not validate aria-checked.
The component is controlled and represents an immediate setting, not a deferred form choice.

Accountable owner

Design systems form foundations owner

Canonical source: src/components/Toggle.tsx

Changes to state meaning or motion require accessibility and interaction review.
A breaking property, token, or behavior change requires design and engineering approval, a migration note, and a major release.
The design asset, implementation, documentation, accessibility contract, and regression coverage must ship in the same change.

Read the system construction standard

Visual specification

These measurements and semantic tokens define the supported visual contract. Local overrides should preserve the same hierarchy and interaction cues.

Target minimum height

44px

Track

40 × 24px

Thumb

16 × 16px

Thumb position

3px off / 25px on

Label gap

10px

Rules

Use on for the enabled/active meaning.
The setting takes effect on activation; use a checkbox or form action when changes are deferred.

Token dependencies

--color-action-primary

On track fill and border.

--color-on-action

Thumb fill.

--color-surface2

Off track fill.

--color-control-border / --color-control-border-strong

Off track and hover boundary.

--color-focus

Track focus outline.

--motion-fast

Track color and thumb movement.

States and behavior

A component is not complete until its passive, interactive, disabled, and exceptional states remain understandable in both themes.

on

Trigger: checked is true.
Visual response: Solid track; thumb translated right.
Behavior: Activation requests false.
Accessibility: aria-checked true.

off

Trigger: checked is false.
Visual response: Surface2 track; thumb at left.
Behavior: Activation requests true.
Accessibility: aria-checked false.

disabled

Trigger: disabled is true.
Visual response: Track and label at 50% opacity.
Behavior: Native button cannot focus or activate.

focus-visible

Trigger: Keyboard focus reaches the switch.
Visual response: 2px focus outline with 3px offset on track.
Behavior: Space or Enter toggles.

Accessibility contract

Semantics, accessible naming, keyboard behavior, focus and announcements are implementation requirements, not optional documentation.

Semantics: Native button with role=switch and aria-checked.
Accessible name: Required visible label is included in the button name.

Keep label text stable between states.
State must be controlled and updated from onChange.
Do not announce on/off again in the label; switch semantics already expose it.

Keyboard behavior

Enter / Space: Toggles the switch.
Tab / Shift+Tab: Moves focus to or from an enabled switch.

Implementation

Use the public package API and preserve the controlled-state, native-attribute, and ref contracts described below.

tsx

import { Toggle } from '@ai-created/ui';

Server Component compatible

Forwards an HTMLButtonElement ref.
onChange receives the next boolean immediately.
The visual track and thumb are aria-hidden.

tsx

<Toggle checked={enabled} onChange={setEnabled} label="Enable notifications" />

Public API

These props and helpers are compatibility contracts. Changes require migration guidance and release notes.

Prop	Type	Default	Contract
checked	boolean	required	Controlled switch state.
onChange	(checked: boolean) => void	required	Called when toggled.
label	string	required	Visible label.
disabled	boolean	false	Disables the switch.
className	string	undefined	Additional classes.

Usage guidance

These rules keep the component recognizable across products without preventing deliberate composition.

Do

Use for settings applied immediately.
Phrase labels as the feature being enabled.

Do not

Do not use for commands such as Send or Save.
Do not use if changing the value requires a separate submit step.

Testing contract

The component should be verified as rendered UI, an interaction model, an accessibility surface, and a theme-aware visual artifact.

Unit

Reflects checked and disabled state and calls onChange with the inverse.
Always uses type button.

Interaction

Pointer, Enter, and Space toggle once; disabled does not.

Accessibility

Role, name, aria-checked, focus order, and focus indicator are valid.

Visual

Capture on/off, hover, focus, disabled, and both themes.

Related specifications

checkbox theme field