Skip to content

Search documentation

Search guides, examples, and component APIs.

Quick links
↑↓ NavigateEnter OpenEsc Close
Get started

Documentation navigation

Components / Actions

Toggle

A native two-state button with pressed semantics.

Last changed in version 0.13.0: Add avatar groups and chips, expand the block gallery, and improve component colors, spacing, and motion.

Interactive showcase

Install

Run in your project
bunx --bun @getweini/cli@latest add toggle

Start with this example

Import the files copied by the install command, then place the component in your Vue template. The text and values in the example belong to your app; change them to fit your task.

Vue
<script setup lang="ts">
import { ref } from 'vue'
import Toggle from './components/ui/toggle/Toggle.vue'

const bold = ref(false)
</script>

<template>
  <Toggle v-model="bold" variant="outline" aria-label="Bold">B</Toggle>
</template>

The native button exposes aria-pressed and data-state. Give it visible text or an ARIA name; disabled toggles cannot update the model and leave the tab order.

When to use it

Editor formatting

Represent an on/off command such as bold with a pressed button.

Persistent view preference

Bind a boolean preference and reflect its current value.

More examples

Bold text

The button communicates the state with aria-pressed.

Bold text
<script setup lang="ts">
import { ref } from 'vue'
import Toggle from './components/ui/toggle/Toggle.vue'

const bold = ref(false)
</script>
<template>
  <Toggle v-model="bold" aria-label="Bold" variant="outline"><strong>B</strong></Toggle>
</template>

Show grid lines

A text label can provide the accessible name directly.

Show grid lines
<script setup lang="ts">
import { ref } from 'vue'
import Toggle from './components/ui/toggle/Toggle.vue'

const showGrid = ref(true)
</script>
<template>
  <Toggle v-model="showGrid">Grid lines</Toggle>
</template>

Complete API

Every public prop, model, event, slot, and exposed member of the installed Vue parts is listed below. “Not set” means you can leave that value out; “Required” means you must provide it. Native HTML attributes also work where the component uses a native element.

Toggle

Complete API for Toggle
NameType or signatureDefaultWhat it does
variantprop"default" | "outline" | undefined"default"Choose the visual treatment for this component.
sizeprop"sm" | "md" | "lg" | undefined"md"Choose the visual size. Medium is the usual default where available.
disabledpropboolean | undefinedNot setPrevent interaction and show the disabled state.
typeprop"button" | "submit" | "reset" | undefined"button"Choose the native HTML control type or action behavior.
modelValuemodelboolean | undefinedfalseCurrent value. Use v-model to keep it in sync with your page.
update:modelValueevent[value: boolean]—Requests a new model value from the parent.
defaultslot(props: { pressed: boolean; }) => unknownRequiredContent shown inside Toggle.
elementexposedHTMLButtonElement | null—Reference to the underlying HTML element.
focusexposed() => void | undefined—Move keyboard focus to this control.
Public type definitions
Public types
// packages/frameworks/vue/components/toggle/types.ts
// ------- IMPORTS -------

import type { toggleSizes, toggleVariants } from './styles'

// ------- TYPES -------

export interface ToggleProps {
  variant?: keyof typeof toggleVariants
  size?: keyof typeof toggleSizes
  disabled?: boolean
  type?: 'button' | 'submit' | 'reset'
}


// packages/frameworks/vue/components/toggle/styles.ts
// Edit toggle variants and sizes here; public visual prop types follow these keys.
export const toggleVariants = {
  default: 'border border-transparent text-foreground hover:bg-secondary',
  outline:
    'border border-control-border bg-clip-padding bg-control text-foreground hover:bg-secondary',
} as const

export const toggleSizes = {
  sm: 'h-8 px-3 text-xs',
  md: 'h-10 px-4 text-sm',
  lg: 'h-12 px-6 text-base',
} as const

Implementation notes

  • Toggle models a boolean pressed state, not a form checkbox value.
  • The default slot can receive { pressed } when the visual content needs to react to state.
  • The press feedback stays still when disabled or when reduced motion is requested.

Accessibility and localization

  • Give a symbol-only toggle an aria-label.
  • Keep the accessible name stable while aria-pressed communicates on and off.

Source contract and editing guidance