Gloss UI Kit v4.4 — Component Library

Toggle

Switch controls for enabling or disabling a single setting. Toggles provide immediate visual feedback with smooth spring physics animation. Use toggles for binary on/off states where the change takes effect immediately without requiring a save action.

Toggle States

Physics The toggle thumb uses spring easing (cubic-bezier(0.34, 1.56, 0.64, 1)) for a bouncy, tactile feel. The track color transitions smoothly while the thumb slides with slight overshoot.

Size Variants

Small (36x20)

Medium (44x24)

Large (52x28)

Small toggle

Medium toggle

Large toggle

Toggle me

Current State: OFF

Spring Animation

Thumb slides with bouncy overshoot easing

Color Transition

Track smoothly fades from gray to blue

Immediate Effect

Changes apply instantly (no save needed)

Examples

Basic Toggle

Simple toggle with a label for on/off settings.

Enable notifications

JSX

<Toggle label="Enable notifications" />

Controlled Toggle

Manage toggle state with React state for controlled behavior.

Notifications (enabled)

JSX

const [notifications, setNotifications] = useState(true);

<Toggle
  label="Notifications"
  checked={notifications}
  onCheckedChange={setNotifications}
/>

Default Checked

Start with the toggle in the on state.

Auto-update enabled

JSX

<Toggle label="Auto-update enabled" defaultChecked />

With On/Off Labels

Add text labels inside the toggle track to clarify the state.

Visibility

Status

JSX

<Toggle label="Visibility" onLabel="ON" offLabel="OFF" size="lg" />
<Toggle label="Status" onLabel="YES" offLabel="NO" size="lg" />

With Helper Text

Add additional context below the toggle.

Dark mode

Switch between light and dark themes

JSX

<Toggle
  label="Dark mode"
  helperText="Switch between light and dark themes"
/>

Error State

Indicate an issue with the toggle setting.

Public profile

Cannot change while verification is pending

JSX

<Toggle
  label="Public profile"
  variant="error"
  helperText="Cannot change while verification is pending"
/>

Success State

Confirm the setting has been applied successfully.

Two-factor authentication

JSX

<Toggle
  label="Two-factor authentication"
  defaultChecked
  variant="success"
/>

Disabled States

Disable interaction for readonly or unavailable settings.

Disabled off

Disabled on

JSX

<Toggle label="Disabled off" disabled />
<Toggle label="Disabled on" disabled defaultChecked />

Variant Styling

Use the variant prop for different visual emphasis.

Default variant

Success variant

Error variant

JSX

<Toggle label="Default variant" defaultChecked />
<Toggle label="Success variant" variant="success" defaultChecked />
<Toggle label="Error variant" variant="error" defaultChecked />

All Sizes Comparison

Compare all three sizes for different use cases.

Small - for dense UIs and tables

Medium - default size for settings

Large - for prominent actions

JSX

<Toggle label="Small" size="sm" />
<Toggle label="Medium" size="md" />
<Toggle label="Large" size="lg" />

Settings Panel Pattern

Common pattern for a settings page with multiple toggles.

Email notifications

Receive updates via email

Auto-save

Save changes automatically

Dark mode

Use dark theme

JSX

<div className="setting-row">
  <div className="setting-info">
    <div className="setting-label">Email notifications</div>
    <div className="setting-desc">Receive updates via email</div>
  </div>
  <Toggle checked={notifications} onCheckedChange={setNotifications} />
</div>

Feature Flags Pattern

Use toggles for enabling/disabling features in admin panels.

Beta features

Enable experimental features (may be unstable)

Analytics tracking

Help us improve by sending anonymous usage data

AI suggestions

Get smart recommendations powered by AI

JSX

<Toggle
  label="Beta features"
  helperText="Enable experimental features (may be unstable)"
/>
<Toggle
  label="Analytics tracking"
  helperText="Help us improve by sending anonymous usage data"
  defaultChecked
/>
<Toggle
  label="AI suggestions"
  helperText="Get smart recommendations powered by AI"
  defaultChecked
  variant="success"
/>

Best Practices

Do

Use for immediate on/off states
Label clearly what the toggle controls
Show current state visually (color/position)
Use for settings that take effect immediately
Place label on the left for list layouts

Don't

Don't use if a save button is required
Don't use for selecting from multiple options
Don't use negative labels ("Disable X")
Don't use toggles for form submissions
Don't mix toggles and checkboxes for similar actions

Toggle Props

Prop	Type	Default	Description
`checked`	`boolean`	-	Controlled on state
`defaultChecked`	`boolean`	`false`	Initial on state (uncontrolled)
`onChange`	`(e: ChangeEvent) => void`	-	Native change event handler
`onCheckedChange`	`(checked: boolean) => void`	-	Convenience handler with boolean value
`label`	`ReactNode`	-	Label text
`onLabel`	`ReactNode`	-	Text shown in track when on
`offLabel`	`ReactNode`	-	Text shown in track when off
`helperText`	`string`	-	Helper text below toggle
`variant`	`'default' \| 'success' \| 'error'`	`'default'`	Visual variant styling
`size`	`'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Toggle size
`disabled`	`boolean`	`false`	Disable the toggle

Accessibility

Role: Uses role="switch" for proper semantics
Keyboard: Space to toggle, Tab to navigate
ARIA: Uses aria-checked to announce state
Focus: Visible focus ring for keyboard navigation
Color: Don't rely solely on color - position also indicates state

Toggle vs Checkbox

Use Toggle When	Use Checkbox When
Change takes effect immediately	Change requires a save/submit action
Single on/off setting	Multiple independent options
Settings/preferences panel	Form with submit button
Mobile-like interfaces	Traditional desktop forms