---
metaTitle: Switcher component | AwesCode UI
meta:
  - name: description
    content: The <AwSwitcher /> component is used to render Switcher - UI Vue component for AwesCode UI.
title: Switcher
---

# Switcher

**Category:** Atom | **Import:** Global

The `AwSwitcher` component is a toggle switch with smooth animations and optional icons.

## Overview

`AwSwitcher` provides a styled toggle switch component that extends `AwCheckbox`. It supports drag gestures, custom colors, icons, and multiple sizes. The switch can be toggled by clicking or dragging.

## Usage

### Basic Example

```markup
<AwSwitcher v-model="enabled" label="Enable feature" />
```

### Different Sizes

```markup
<AwSwitcher v-model="enabled" size="sm" label="Small" />
<AwSwitcher v-model="enabled" size="md" label="Medium" />
<AwSwitcher v-model="enabled" size="lg" label="Large" />
```

### With Custom Colors

```markup
<AwSwitcher 
    v-model="enabled" 
    active-color="success"
    inactive-color="mono-400"
    label="Custom colors"
/>
```

### With Icons

```markup
<AwSwitcher 
    v-model="enabled" 
    icon="awesio/check"
    off-icon="awesio/close"
    label="With icons"
/>
```

### Icon in Toggle Circle

```markup
<AwSwitcher 
    v-model="enabled" 
    icon="awesio/check"
    icon-place-in
    label="Icon in circle"
/>
```

## API

### Props

| Name | Description | Type | Required | Default |
|------|-------------|------|----------|---------|
| value | Value emitted when checked | `String` / `Number` / `Boolean` / `Object` | `false` | `'on'` |
| checked | Checked state | `Array` / `Boolean` / `Number` | `false` | `false` |
| size | Switch size (sm, md, lg) | `String` | `false` | `'md'` | Must be: sm, md, lg |
| activeColor | Background color when active | `String` | `false` | `'success'` |
| inactiveColor | Background color when inactive | `String` | `false` | `''` |
| icon | Icon name when active | `String` | `false` | `''` |
| offIcon | Icon name when inactive | `String` | `false` | `''` |
| iconColor | Icon color | `String` | `false` | `''` |
| hideIcon | Hide icons completely | `Boolean` | `false` | `false` |
| iconPlaceIn | Place icon inside toggle circle | `Boolean` | `false` | `false` |

All props from `AwCheckbox` are also supported.

### Slots

| Name | Description | Props | Default Slot Content |
|------|-------------|-------|---------------------|
| default | Custom switch element | `{ id, checked, onChange, setError, value }` | Default switch input |
| label | Custom label content | `{ label, value, isChecked }` | Label text |
| toggler-icon | Custom icon in toggle circle | - | Default icon |

### Events

| Name | Payload | Description |
|------|---------|-------------|
| change | `value` | Emitted when switch state changes |

## Component Behavior

### Toggle Interaction

The component supports two methods of toggling:

**Click to toggle:**
- Single click/tap anywhere on the switch toggles the state
- Works on the toggle circle, background, or label

**Drag to toggle:**
- Click/touch and drag horizontally to switch states
- Drag threshold is 5 pixels to prevent accidental toggles
- Visual feedback shows state change during drag
- Works with both mouse and touch events

### Drag Detection

The component intelligently distinguishes between clicks and drags:
- **Threshold:** 5 pixels of horizontal movement
- **Click:** Movement less than threshold triggers immediate toggle
- **Drag:** Movement exceeds threshold, switch follows drag direction
- **Right drag (unchecked → checked):** Turns switch on when dragging right
- **Left drag (checked → unchecked):** Turns switch off when dragging left

### Icon Display

Icons are displayed based on size and props:
- **sm size:** Icons are never shown (too small)
- **md size:** Icons shown at 12px, can be placed outside or inside toggle circle
- **lg size:** Icons shown at 22px, can be placed outside or inside toggle circle

**Icon placement:**
- `iconPlaceIn={false}` (default): Icons appear outside the toggle circle (active on left, inactive on right)
- `iconPlaceIn={true}`: Single icon appears inside the moving toggle circle

**Icon props:**
- `icon`: Icon shown when switch is active/on
- `offIcon`: Icon shown when switch is inactive/off (defaults to `icon` value if not specified)
- `hideIcon`: Completely hides all icons regardless of size

For a complete list of available icons, see [Built-in Icons](/reference/icons).

### Color System

Background colors adapt to switch state:
- **Active (checked):** Uses `activeColor` prop (default: `'success'`)
- **Inactive (unchecked):** Uses `inactiveColor` prop (default: transparent/gray)
- Colors accept any valid color from the AwesCode UI color system
- Common active colors: `success`, `info`, `warning`, `error`, `accent`

For a complete list of available colors, see [Built-in Colors](/reference/colors).

### State Management

Extends `AwCheckbox` for state handling:
- Supports `v-model` for two-way binding
- `checked` prop accepts Boolean, Array, or Number
- `value` prop specifies the value emitted when checked
- Internal state tracks both checkbox state and drag position
- Watch updates internal state when external `checked` prop changes

### Event Listeners

The component dynamically manages event listeners:
- **Mouse/touch down:** Initiates drag detection, adds move/up listeners
- **Mouse/touch move:** Tracks drag position, updates visual state
- **Mouse/touch up:** Completes toggle action, removes listeners
- **Cleanup:** All listeners properly removed on component destroy

### Touch Support

Full touch gesture support for mobile devices:
- Touch events (touchstart, touchmove, touchend) handled separately from mouse
- Uses `screenX` for accurate position tracking across devices
- Prevents unwanted interactions during drag operations

## Related Components

- `AwCheckbox` - Checkbox component (extended by switcher)
- `AwRadio` - Radio button component
- `AwIcon` - Icon component

## Notes

- **Import Method:** Global - Available as atom component
- Extends `AwCheckbox` for checkbox functionality
- Supports drag gestures (mouse and touch) for toggling
- Icons are only shown for md and lg sizes
- Icon size adapts based on switch size (22px for lg, 12px for md)
- Drag threshold is 5 pixels to prevent accidental toggles
- Supports partial/indeterminate state from checkbox