Switch

Material Design 3 switch component for toggling between on and off states

Switch

Native Contract And Imports

Individual example prerequisites (including composition and demo actions):

@import "@duskmoon-dev/core/base.css";
@import "@duskmoon-dev/core/themes/sunshine";
@import "@duskmoon-dev/core/components/switch.css";
@import "@duskmoon-dev/core/components/form-group.css";

base.css supplies global focus/utility definitions and shared spacing/shape tokens; use your framework reset when appropriate. Substitute the Moonlight theme for dark forms.

Aggregate: @duskmoon-dev/core with Tailwind v4; no-Tailwind: @duskmoon-dev/core/standalone.css. Individual: @duskmoon-dev/core/components/switch.css plus base/theme and form-group.css for associated labels/help. Extensionless components/switch exports generated css and constructable styles, not a behavior runtime.

Use native inputs for values, selection, constraints, submission and reset. Actual disabled or fieldset disabled owns semantic disabling. Use .validator for native interaction-based errors and add .validator-success for native success. Explicit aria-invalid="true" wins over those states and color modifiers, including focus. Supply described error text as well as color. See Validator and Field composition.

Switch / Toggle is an on/off form control. .switch is the MD3 control; legacy input[type="checkbox"].toggle retains its compact appearance through components/toggle-switch.css, form.css or toggle.css. .toggle-btn is a separate pressed action button, documented under Toggle Button. All use native checked state except actions, whose aria-pressed updates belong to applications.

Switches toggle the state of a single item on or off. @duskmoon-dev/core provides a Material Design 3 switch component with smooth animations and multiple variants.

Basic Usage

Simply add the .switch class to an <input type="checkbox">:

Basic Switch

With Label

Wrap the switch in a label for better UX:

Switch with Label

Checked State

Checked Switch

Sizes

Five sizes are available:

Switch Sizes

Color Variants

Primary (Default)

Primary Switch

Secondary

Secondary Switch

Tertiary

Tertiary Switch

Success

Success Switch

Warning

Warning Switch

Error

Error Switch

Info

Info Switch

All Colors Comparison

All Color Variants

States

Disabled

Disabled Switches

Switch Groups

Vertical Group

Vertical Switch Group

Horizontal Group

Horizontal Switch Group

Form Integration

Switch in Form

Privacy Settings

Best Practices

When to Use

Switches are best for:

  • Instant changes: Settings that take effect immediately
  • On/off states: Binary choices like enable/disable features
  • System settings: Preferences and configurations

When Not to Use

Avoid switches for:

  • Form submission: Use checkboxes instead when changes require user confirmation
  • Multiple options: Use radio buttons or select dropdowns
  • Actions with delay: If the change requires processing time, consider a button

Accessibility

  • Use semantic <label> elements to associate labels with switches
  • Provide descriptive label text that explains what the switch controls
  • Support keyboard navigation (built-in with native inputs)
  • Ensure sufficient color contrast in both states

Touch Targets

The switch provides adequate touch targets. For mobile-first designs, use larger sizes:

Mobile-Friendly Switch

API Reference

Class Names

Class Description
.switch Base switch styling (required, on input element)
.switch-xs Extra small size (2rem width)
.switch-sm Small size (2.5rem width)
.switch-md Medium size (3.25rem width, default)
.switch-lg Large size (4rem width)
.switch-xl Extra large size (4.75rem width)
.switch-primary Primary color variant (default)
.switch-secondary Secondary color variant
.switch-tertiary Tertiary color variant
.switch-success Success color variant
.switch-warning Warning color variant
.switch-error Error color variant
.switch-info Info color variant
.switch-label Label wrapper for switch + text
.switch-group Container for vertical switch group
.switch-group-horizontal Horizontal layout modifier

HTML Structure

Simple switch:

<input type="checkbox" class="switch" aria-label="Example switch" />

With label:

<label class="switch-label">
  <input type="checkbox" class="switch" />
  <span>Label text</span>
</label>

Switch group:

<div class="switch-group">
  <label class="switch-label">
    <input type="checkbox" class="switch" name="option1" />
    <span>Option 1</span>
  </label>
  <label class="switch-label">
    <input type="checkbox" class="switch" name="option2" />
    <span>Option 2</span>
  </label>
</div>

States

State How to Apply
Checked checked attribute
Disabled disabled attribute
Focus Automatic via :focus-visible

Ghost Variant

The ghost variant removes the visible track border and background when off — creates a minimal toggle.

Ghost Switch

  • Checkbox - Multi-select form control
  • Radio - Single selection input
  • Button - For action triggers