Components

Toggle

Switch a button between pressed and unpressed states.

Install with the CLI

npx @vyui/cli add toggle

Overview

VyToggle is a two-state button for options such as bold text, favorites, or pinned tools. It wraps the core toggle primitive with semantic colors, four visual variants, responsive sizing, and optional Iconify content.

Usage

Bind the pressed state with v-model. Add an accessibility-label when the toggle contains only an icon.

Text content

The default slot replaces the built-in icon, so it can contain text or a custom composition.

Disabled

Set disabled to prevent taps and dim the control, in both the unpressed and pressed states.

Features and behavior

Tapping an enabled toggle inverts modelValue and emits update:modelValue.
The kit component defaults modelValue to false; use v-model to retain user changes in application state.
disabled prevents taps, applies disabled semantics, and dims the control.
The default slot takes precedence over icon.
The root exposes data-state="on" or data-state="off" and matching ui-on or ui-off classes through the core primitive.
Additional attributes, including native Lynx accessibility attributes, are inherited by the root toggle.

Props

Prop	Type	Default	Description
`modelValue`	`boolean`	`false`	Pressed state, normally bound with `v-model`.
`disabled`	`boolean`	`false`	Prevents interaction and applies disabled styling and semantics.
`color`	`Color`	`'primary'`	Semantic color used for the pressed appearance.
`variant`	`'solid' \| 'outline' \| 'soft' \| 'ghost'`	`'ghost'`	Pressed-state surface and foreground treatment.
`size`	`'sm' \| 'md' \| 'lg' \| 'xl'`	`'md'`	Padding, text size, gap, and built-in icon size.
`icon`	`string`	`undefined`	Iconify name rendered when the default slot is empty.
`class`	`any`	`undefined`	Classes merged onto the root toggle.
`ui`	`Partial<Record<ToggleSlot, any>>`	`undefined`	Per-instance theme slot overrides.

Color defaults to primary, secondary, success, info, warning, error, or neutral, and supports consumer registry extensions.

Emits

Event	Payload	Description
`update:modelValue`	`boolean`	Emitted with the inverted pressed state after an enabled tap.

Slots

Slot	Props	Description
`default`	—	Replaces the built-in icon.

Styling and theming

Override globally through appConfig.ui.toggle or locally with ui.

UI slot	Purpose
`base`	Root layout, shape, typography, spacing, surface, and interaction states.
`icon`	Built-in icon size and foreground color.

The theme combines color, variant, size, and the internal pressed state.

Variant	Pressed appearance
`solid`	Semantic filled surface with a white icon.
`outline`	Semantic border and foreground with a light active surface.
`soft`	Light semantic surface and semantic foreground.
`ghost`	Transparent surface with semantic foreground and active feedback.

The unpressed state uses a neutral icon and neutral active feedback regardless of color. The size variant changes root spacing and the icon slot from size-5 through size-7.

Accessibility

The core primitive exposes the root as a focusable native button and announces pressed or not pressed. Disabled toggles use the native disabled trait.

Provide accessibility-label for icon-only toggles. Text in the default slot gives sighted users context, but an explicit native label remains the safest choice when the control's purpose is not self-evident. The current accessibility layer targets Lynx native attributes; web ARIA bridging is not currently added by the primitive.

Platform notes

The component renders a Lynx view through the core primitive and responds to the Lynx tap event.
Lynx SVG does not inherit currentColor, so the theme places foreground classes directly on the built-in icon slot.
The default theme is light-mode-only.

Built on `@vyui/core`

VyToggle composes the headless @vyui/core toggle primitive. Use it directly when you need full control over markup and styling.

`Toggle` props

Prop	Default	Type
`as`	`"view"`	`AsTag \| Component \| undefined` The element or component this component should render as. Can be overwritten by `asChild`.
`asChild`	—	`boolean \| undefined` Change the default rendered element for the one passed as a child, merging their props and behavior. Use this when you need a component to render through a child element while keeping the primitive's props and behavior.
`defaultValue`	—	`boolean \| undefined` The pressed state of the toggle when it is initially rendered. Use when you do not need to control its open state.
`disabled`	`false`	`boolean \| undefined` When `true`, prevents the user from interacting with the toggle.
`modelValue`	`undefined`	`boolean \| null \| undefined` The controlled pressed state of the toggle. Can be bind as `v-model`.

Toggle Group for a related set of single- or multiple-selection toggles.
Switch for an immediately applied on/off setting.
Button for a one-time action without persistent pressed state.

Toast

Show transient feedback with optional actions, progress, stacking, and swipe dismissal.

Toggle Group

Select one or multiple values from a connected set of toggles.