Switch

updated

Is this a checkbox?

Demo

Open Props in the corner of the example to try color, size and disabled.

color fills the track when the switch is on, in Button's colours or your own. primary is the default. The edge takes the colour's text shade, which keeps 3:1 against the page where a bright warning track doesn't. Off, it keeps the --input edge, so a row of switches that are off reads as one set. An invalid switch turns red whatever its colour.

size runs from xs, 16px tall, to xl, 32px, in steps of 4px. md, the default, is 24px by 39px, between shadcn's switch and Material's; xl is Material's 52px by 32px. The width, handle, icons and state layer all scale with the height.

Installation

Usage

<script setup lang="ts">
import { Field, FieldLabel } from '@/components/ui/field'
import { Switch } from '@/components/ui/switch'

const airplane = ref(false)
</script>

<template>
  <Field orientation="horizontal">
    <Switch v-model="airplane" />
    <FieldLabel>Airplane mode</FieldLabel>
  </Field>
</template>

Use a switch when the change applies right away. If it waits for a Save button, use a Checkbox instead.

Turn it on, and the handle grows and slides across with a little bounce. Press it, and the handle swells. Hover and press get the same soft circle as Checkbox.

Inside a Field, it works as usual.

Examples

Icons

Use the checked-icon and unchecked-icon slots, or just one of them. The "on" icon spins in as the switch turns on. Add an "off" icon, and the handle stays big in both states to fit it.

Icons look best from lg up.

Icons

Description

For a settings row, put the label and description first and the switch after them; the label grows to push the switch to the end of the row.

Description

Anonymous crash reports and feature usage, to help us fix problems.

Invalid

Invalid
Delivery needs your location.

Touch target

Smaller than a finger? Add touch-target: expand when it stands alone, wrapper when it sits close to others. How it works.

With wrapper, the label moves along with the switch.

Touch target

API Reference

class is also accepted and merged over the base classes.

Data attributes

data-slotAttributesDescription
switchdata-state, data-color, data-size, data-disabled, data-touch-target, data-unchecked-iconThe track.
switch-thumbdata-stateThe square the handle moves in.
switch-handle—The round handle.

Changelog

  1. registry 0.22.0

    ac0cc05 — Checkbox, Radio, Switch and Slider no longer declare as and asChild, as Rating already does: Reka's slot cloned the control's own indicator, thumb or track into the root, which left an inert control. The props are gone from their API tables too.

  2. registry 0.21.0

    e5495ef — size works the same way everywhere. Every component exports its size type (AlertSize, BadgeSize, CardSize, CheckboxSize, RadioSize, SwitchSize, EmptySize, InputFloatingSize, ItemSize, ListboxSize, SeparatorSize, SliderSize, StepperSize, TabsSize, TextareaSize, TimelineSize) and the props take it without null; Button-based parts take ButtonSize, Input TextControlSize, SelectTrigger SelectSize and Tree TreeSize. ToggleGroup and ToolbarToggleGroup carry data-size on the group as well. Table's row heights moved into tableSize, so a class on DataTable's ui.table overrides --table-row-h at every size, not only at md.

  3. registry 0.13.0

    5a478d3 — Checkbox, Radio, Switch, Slider, Progress, Stepper and TabsList take color: primary (the default), neutral, destructive, success, warning, info, or any name you declare on [data-slot][data-color="<name>"], as on Button. The root carries data-color. Whatever they draw straight on the page takes the colour's --tone-text: a checked edge, the radio's dot, the default slider's range and thumb, the progress bar and the tab line. That keeps a bright success, warning or info at 3:1 against the page. Fills with something on them, like the checked box, the switch track and the active step, keep --tone. On the choice controls the unchecked edge stays --input and an invalid control still turns destructive. Keyboard focus rings a control in a colour other than primary in its --tone-text, red once it's invalid. CheckboxGroup and RadioGroup pass their color to every control in them without one, and ChoiceGroup takes color for the selected card's edge, the focused card's ring and the selected row's tint. Switch, Checkbox, Radio and Slider now set data-size, md by default. They need the @kappa-ui/core release that lets tone-control follow data-color.

    Recoloured Switch, Checkbox, Radio or Slider with class="[--tone:…] [--tone-foreground:…]", as the theming page used to suggest? Their edges and marks now read --tone-text, so add [--tone-text:…] to the class, or use color.

  4. core 0.10.0

    5a478d3 — tone-control works with a color prop. On an element with data-slot and data-color it leaves --tone, --tone-foreground and --tone-text to the [data-slot][data-color] rules, so the control takes that tone, and it keeps --input as the unchecked edge. A colour other than primary also rings the control in its --tone-text. Any other element gets primary exactly as before, now including --tone-text, so copies of Switch, Checkbox, Radio and Slider made before the prop look the same. tone-invalid now turns --tone-text destructive along with the rest of the tone, so edges, marks and rings drawn in it go red on an invalid control too. Copies made before the prop don't read --tone-text, so they look the same. choice-row tints a selected option in its group's tone when the group has data-slot and data-color, and in primary when it doesn't.

  5. registry 0.10.0

    0f38faa — Switch, Checkbox, Radio and Slider take their tone from core's tone-control and tone-invalid utilities instead of a dozen variable assignments each, so they need the @kappa-ui/core release that adds them. They look the same, and a [--tone:…] class still recolours them. Long class strings across the components are now wrapped by variant group.