Switch

A Switch component is a toggleable UI control that allows users to choose between two states, typically used for enabling or disabling a setting. It provides a visual representation of an on/off state with smooth animations and proper accessibility support.

Features

• Three size variants: small, medium, and large
• Support for labels with left or right positioning
• Disabled state support
• Error state with error message display
• Keyboard navigation support
• Full ARIA support for accessibility
• Customizable through CSS variables

Usage

<script>
    import Switch from '$lib/components/Switch/Switch.svelte';
</script>

<Switch label="Enable notifications" />

Props

Prop	Type	Default	Description
checked	boolean	false	The controlled checked state of the switch
label	string	''	Label text for the switch
disabled	boolean	false	Whether the switch is disabled
required	boolean	false	Whether the switch is required
name	string	''	Name attribute for the input element
size	'sm' \| 'md' \| 'lg'	'md'	Size variant of the switch
error	string	''	Error message to display
ariaLabel	string	''	Aria label for accessibility
labelPosition	'left' \| 'right'	'right'	Position of the label relative to the switch

Events

The Switch component emits a change event when the state changes. The event detail contains the new checked state.

<Switch 
    label="Dark mode" 
    on:change={(e) => console.log('New state:', e.detail.checked)} 
/>

Examples

Basic Usage

<Switch label="Enable notifications" />

With Left Label

<Switch 
    label="Dark mode" 
    labelPosition="left" 
/>

Different Sizes

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

Disabled State

<Switch 
    label="Disabled switch" 
    disabled 
/>

With Error State

<Switch 
    label="Terms and conditions" 
    error="You must accept the terms and conditions" 
    required 
/>

Controlled Component

<script>
    let isEnabled = false;
</script>

<Switch 
    label="Controlled switch"
    checked={isEnabled}
    on:change={(e) => isEnabled = e.detail.checked}
/>

Styling

The Switch component can be customized using CSS variables. Here’s a comprehensive list of all available CSS variables and their purposes:

Core Variables

:root {
    /* Colors */
    --rebel-brand: #007bff;        /* Switch active color */
    --rebel-bg-light: #ffffff;     /* Thumb color when active */
    --rebel-border: #d1d5db;       /* Border color */
    --rebel-border-light: #e5e7eb; /* Background color when inactive */
    --rebel-text-secondary: #6b7280; /* Thumb color when inactive */
    --rebel-text-primary: #1f2937; /* Label text color */
    
    /* States */
    --rebel-disabled-bg: #f3f4f6;  /* Background color when disabled */
    --rebel-text-disabled: #9ca3af; /* Thumb color when disabled */
    --rebel-error: #ef4444;        /* Error state color */
    --rebel-focus-ring: rgba(59, 130, 246, 0.5); /* Focus ring color */
    
    /* Sizes (automatically set based on size prop) */
    --switch-width: 40px;          /* Width of the switch (md size) */
    --switch-height: 22px;         /* Height of the switch (md size) */
    
    /* Animation */
    --rebel-ease-out: cubic-bezier(0.4, 0, 0.2, 1); /* Transition timing function */
}

Size Variants

The component includes three predefined size variants that set their own CSS variables:

/* Small */
.sm {
    --switch-width: 32px;
    --switch-height: 18px;
    font-size: 0.75rem;
}

/* Medium (default) */
.md {
    --switch-width: 40px;
    --switch-height: 22px;
    font-size: 0.875rem;
}

/* Large */
.lg {
    --switch-width: 48px;
    --switch-height: 26px;
    font-size: 1rem;
}

Customization Examples

Here are some examples of common customizations:

1. Custom colors:

.switch {
    --rebel-brand: #0f172a;        /* Dark mode switch */
    --rebel-bg-light: #f8fafc;     /* Light thumb color */
}

2. Larger switch:

.switch {
    --switch-width: 60px;
    --switch-height: 30px;
}

3. Custom animation:

.switch {
    --rebel-ease-out: cubic-bezier(0.68, -0.55, 0.265, 1.55); /* Bouncy animation */
}

CSS Structure

The Switch component uses the following class structure:

• .switch-container - The outer container
• .switch-label - The label wrapper
• .switch-wrapper - The switch input wrapper
• .switch - The switch track
• .thumb - The switch thumb/handle
• .error-message - Error message container

Each element can be styled using CSS variables or direct CSS properties. The component also includes modifier classes for different states:

• .disabled - Applied when the switch is disabled
• .error - Applied when there’s an error
• .label-left - Applied when label is positioned left
• .label-right - Applied when label is positioned right
• .sm, .md, .lg - Size variant classes

Accessibility

The Switch component follows WAI-ARIA best practices for toggle switches:

• Uses role="switch" for proper semantic meaning
• Supports keyboard navigation (Space and Enter keys)
• Includes proper aria labels and states
• Provides visual feedback for focus state
• Maintains proper contrast ratios for all states

Best Practices

1. Always provide a clear, descriptive label
2. Use the switch for boolean (on/off) settings only
3. Position labels consistently across your interface
4. Provide immediate visual feedback when the state changes
5. Use error messages to clearly communicate validation issues

API Reference

Types

type SwitchSize = 'sm' | 'md' | 'lg';

Events

interface SwitchChangeEvent {
    checked: boolean;
}

The component dispatches a change event with the above type when the switch state changes.