v3.0.0-alpha.9

Switch

SwitchGitHub
A control that toggles between two states.

Usage

Use the v-model directive to control the checked state of the Switch.

<script setup lang="ts">
const value = ref(true)
</script>

<template>
  <USwitch v-model="value" />
</template>

Use the default-value prop to set the initial value when you do not need to control its state.

<template>
  <USwitch default-value />
</template>

Label

Use the label prop to set the label of the Switch.

<template>
  <USwitch label="Check me" />
</template>

When using the required prop, an asterisk is be added next to the label.

<template>
  <USwitch required label="Check me" />
</template>

Description

Use the description prop to set the description of the Switch.

This is a checkbox.

<template>
  <USwitch label="Check me" description="This is a checkbox." />
</template>

Icon

Use the checked-icon and unchecked-icon props to set the icons of the Switch when checked and unchecked.

<template>
  <USwitch
    unchecked-icon="i-lucide-x"
    checked-icon="i-lucide-check"
    default-value
    label="Check me"
  />
</template>

Loading

Use the loading prop to show a loading icon on the Switch.

<template>
  <USwitch loading default-value label="Check me" />
</template>

Loading Icon

Use the loading-icon prop to customize the loading icon. Defaults to i-lucide-refresh-ccw.

<template>
  <USwitch loading loading-icon="i-lucide-repeat-2" default-value label="Check me" />
</template>
You can customize this icon globally in your app.config.ts under ui.icons.loading key.

Color

Use the color prop to change the color of the Switch.

<template>
  <USwitch color="neutral" default-value label="Check me" />
</template>

Size

Use the size prop to change the size of the Switch.

<template>
  <USwitch size="xl" default-value label="Check me" />
</template>

Disabled

Use the disabled prop to disable the Switch.

<template>
  <USwitch disabled label="Check me" />
</template>

API

Props

Prop Default Type
as

'div'

any

The element or component this component should render as.

modelValue

boolean

color

primary

"error" | "primary" | "secondary" | "success" | "info" | "warning" | "neutral"

size

md

"md" | "xs" | "sm" | "lg" | "xl"

loading

boolean

When true, the loading icon will be displayed.

loadingIcon

appConfig.ui.icons.loading

string

The icon when the loading prop is true.

checkedIcon

string

Display an icon when the switch is checked.

uncheckedIcon

string

Display an icon when the switch is unchecked.

label

string

description

string

defaultValue

boolean

The state of the switch when it is initially rendered. Use when you do not need to control its state.

name

string

The name of the switch. Submitted with its owning form as part of a name/value pair.

value

string

The value given as data when submitted with a name.

disabled

boolean

When true, prevents the user from interacting with the switch.

required

boolean

When true, indicates that the user must check the switch before the owning form can be submitted.

id

string

ui

PartialString<{ root: string; base: string[]; container: string; thumb: string; icon: string[]; wrapper: string; label: string; description: string; }>

Slots

Slot Type
label

{ label?: string | undefined; }

description

{ description?: string | undefined; }

Emits

Event Type
change

[payload: Event]

update:modelValue

[payload: boolean]

Theme

app.config.ts
export default defineAppConfig({
  ui: {
    switch: {
      slots: {
        root: 'relative flex items-start',
        base: [
          'inline-flex items-center shrink-0 rounded-full border-2 border-transparent focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-[var(--ui-bg)] data-[state=unchecked]:bg-[var(--ui-bg-accented)]',
          'transition-colors duration-200'
        ],
        container: 'flex items-center',
        thumb: 'group pointer-events-none block rounded-full bg-[var(--ui-bg)] shadow-lg ring-0 transition-transform duration-200 data-[state=unchecked]:translate-x-0 data-[state=unchecked]:rtl:-translate-x-0 flex items-center justify-center',
        icon: [
          'absolute shrink-0 group-data-[state=unchecked]:text-[var(--ui-text-dimmed)] opacity-0 size-10/12',
          'transition-[color,opacity] duration-200'
        ],
        wrapper: 'ms-2',
        label: 'block font-medium text-[var(--ui-text)]',
        description: 'text-[var(--ui-text-muted)]'
      },
      variants: {
        color: {
          primary: {
            base: 'data-[state=checked]:bg-[var(--ui-primary)] focus-visible:ring-[var(--ui-primary)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-primary)]'
          },
          secondary: {
            base: 'data-[state=checked]:bg-[var(--ui-secondary)] focus-visible:ring-[var(--ui-secondary)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-secondary)]'
          },
          success: {
            base: 'data-[state=checked]:bg-[var(--ui-success)] focus-visible:ring-[var(--ui-success)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-success)]'
          },
          info: {
            base: 'data-[state=checked]:bg-[var(--ui-info)] focus-visible:ring-[var(--ui-info)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-info)]'
          },
          warning: {
            base: 'data-[state=checked]:bg-[var(--ui-warning)] focus-visible:ring-[var(--ui-warning)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-warning)]'
          },
          error: {
            base: 'data-[state=checked]:bg-[var(--ui-error)] focus-visible:ring-[var(--ui-error)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-error)]'
          },
          neutral: {
            base: 'data-[state=checked]:bg-[var(--ui-bg-inverted)] focus-visible:ring-[var(--ui-border-inverted)]',
            icon: 'group-data-[state=checked]:text-[var(--ui-text-highlighted)]'
          }
        },
        size: {
          xs: {
            base: 'w-7',
            container: 'h-4',
            thumb: 'size-3 data-[state=checked]:translate-x-3 data-[state=checked]:rtl:-translate-x-3',
            wrapper: 'text-xs'
          },
          sm: {
            base: 'w-8',
            container: 'h-4',
            thumb: 'size-3.5 data-[state=checked]:translate-x-3.5 data-[state=checked]:rtl:-translate-x-3.5',
            wrapper: 'text-xs'
          },
          md: {
            base: 'w-9',
            container: 'h-5',
            thumb: 'size-4 data-[state=checked]:translate-x-4 data-[state=checked]:rtl:-translate-x-4',
            wrapper: 'text-sm'
          },
          lg: {
            base: 'w-10',
            container: 'h-5',
            thumb: 'size-4.5 data-[state=checked]:translate-x-4.5 data-[state=checked]:rtl:-translate-x-4.5',
            wrapper: 'text-sm'
          },
          xl: {
            base: 'w-11',
            container: 'h-6',
            thumb: 'size-5 data-[state=checked]:translate-x-5 data-[state=checked]:rtl:-translate-x-5',
            wrapper: 'text-base'
          }
        },
        checked: {
          true: {
            icon: 'group-data-[state=checked]:opacity-100'
          }
        },
        unchecked: {
          true: {
            icon: 'group-data-[state=unchecked]:opacity-100'
          }
        },
        loading: {
          true: {
            icon: 'animate-spin'
          }
        },
        required: {
          true: {
            label: "after:content-['*'] after:ms-0.5 after:text-[var(--ui-error)]"
          }
        },
        disabled: {
          true: {
            base: 'cursor-not-allowed opacity-75',
            label: 'cursor-not-allowed opacity-75',
            description: 'cursor-not-allowed opacity-75'
          }
        }
      },
      defaultVariants: {
        color: 'primary',
        size: 'md'
      }
    }
  }
})

Slider

An input to select a numeric value within a range.

Table

A responsive table element to display data in rows and columns.