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 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-loader-circle.

<template>
  <USwitch loading loading-icon="i-lucide-loader" default-value label="Check me" />
</template>

You can customize this icon globally in your app.config.ts under ui.icons.loading key.

You can customize this icon globally in your vite.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.

color

'primary'

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

size

'md'

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

loading

boolean

When true, the loading icon will be displayed.

loadingIcon

appConfig.ui.icons.loading

string | object

The icon when the loading prop is true.

checkedIcon

string | object

Display an icon when the switch is checked.

uncheckedIcon

string | object

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.

disabled

boolean

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

name

string

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

id

string

required

boolean

When true, indicates that the user must set the value before the owning form can be submitted.

value

string

The value given as data when submitted with a name.

modelValue

undefined

boolean

ui

{ root?: ClassNameValue; base?: ClassNameValue; container?: ClassNameValue; thumb?: ClassNameValue; icon?: ClassNameValue; wrapper?: ClassNameValue; label?: ClassNameValue; description?: ClassNameValue; }

Slots

Slot Type
label

{ label?: string | undefined; }

description

{ description?: string | undefined; }

Emits

Event Type
update:modelValue

[value: boolean]

change

[event: Event]

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-2 focus-visible:outline-offset-2 data-[state=unchecked]:bg-accented',
          'transition-[background] duration-200'
        ],
        container: 'flex items-center',
        thumb: 'group pointer-events-none rounded-full bg-default 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-dimmed opacity-0 size-10/12',
          'transition-[color,opacity] duration-200'
        ],
        wrapper: 'ms-2',
        label: 'block font-medium text-default',
        description: 'text-muted'
      },
      variants: {
        color: {
          primary: {
            base: 'data-[state=checked]:bg-primary focus-visible:outline-primary',
            icon: 'group-data-[state=checked]:text-primary'
          },
          secondary: {
            base: 'data-[state=checked]:bg-secondary focus-visible:outline-secondary',
            icon: 'group-data-[state=checked]:text-secondary'
          },
          success: {
            base: 'data-[state=checked]:bg-success focus-visible:outline-success',
            icon: 'group-data-[state=checked]:text-success'
          },
          info: {
            base: 'data-[state=checked]:bg-info focus-visible:outline-info',
            icon: 'group-data-[state=checked]:text-info'
          },
          warning: {
            base: 'data-[state=checked]:bg-warning focus-visible:outline-warning',
            icon: 'group-data-[state=checked]:text-warning'
          },
          error: {
            base: 'data-[state=checked]:bg-error focus-visible:outline-error',
            icon: 'group-data-[state=checked]:text-error'
          },
          neutral: {
            base: 'data-[state=checked]:bg-inverted focus-visible:outline-inverted',
            icon: 'group-data-[state=checked]: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-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'
      }
    }
  }
})
vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import ui from '@nuxt/ui/vite'

export default defineConfig({
  plugins: [
    vue(),
    ui({
      ui: {
        switch: {
          slots: {
            root: 'relative flex items-start',
            base: [
              'inline-flex items-center shrink-0 rounded-full border-2 border-transparent focus-visible:outline-2 focus-visible:outline-offset-2 data-[state=unchecked]:bg-accented',
              'transition-[background] duration-200'
            ],
            container: 'flex items-center',
            thumb: 'group pointer-events-none rounded-full bg-default 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-dimmed opacity-0 size-10/12',
              'transition-[color,opacity] duration-200'
            ],
            wrapper: 'ms-2',
            label: 'block font-medium text-default',
            description: 'text-muted'
          },
          variants: {
            color: {
              primary: {
                base: 'data-[state=checked]:bg-primary focus-visible:outline-primary',
                icon: 'group-data-[state=checked]:text-primary'
              },
              secondary: {
                base: 'data-[state=checked]:bg-secondary focus-visible:outline-secondary',
                icon: 'group-data-[state=checked]:text-secondary'
              },
              success: {
                base: 'data-[state=checked]:bg-success focus-visible:outline-success',
                icon: 'group-data-[state=checked]:text-success'
              },
              info: {
                base: 'data-[state=checked]:bg-info focus-visible:outline-info',
                icon: 'group-data-[state=checked]:text-info'
              },
              warning: {
                base: 'data-[state=checked]:bg-warning focus-visible:outline-warning',
                icon: 'group-data-[state=checked]:text-warning'
              },
              error: {
                base: 'data-[state=checked]:bg-error focus-visible:outline-error',
                icon: 'group-data-[state=checked]:text-error'
              },
              neutral: {
                base: 'data-[state=checked]:bg-inverted focus-visible:outline-inverted',
                icon: 'group-data-[state=checked]: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-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'
          }
        }
      }
    })
  ]
})

Changelog

61b60 — feat: allow passing a component instead of a name (#4766)

5cb65 — feat: import @nuxt/ui-pro components

7133f — fix: broken types for update:model-value event (#4853)

e6e51 — fix: class should have priority over ui prop

39c86 — fix: refactor types after @nuxt/module-builder upgrade (#3855)

Slider

An input to select a numeric value within a range.

Textarea

A textarea element to input multi-line text.