StellarUI

<stellar-switch>

Properties

Preview

Markup

Copy

<stellar-switch
  checked
  label="Email alerts"
  description="Send a notification for new activity."
  prefix-label="Off"
  suffix-label="On"
  prefix-icon="mdi:weather-night"
  suffix-icon="mdi:white-balance-sunny"
  value="on"
>
</stellar-switch>

API

Complete props, events, slots, and implementation notes for the shipped switch.

Props

Prop	Type	Default
`tone`	`neutral \| primary \| secondary \| tertiary \| error`	`neutral`
`size`	`xs \| sm \| md \| lg \| xl`	`md`
`orientation`	`vertical \| horizontal`	`vertical`
`label`	`string`	`''`
`description`	`string`	`''`
`error`	`string`	`''`
`checked`	`boolean`	`false`
`indeterminate`	`boolean`	`false`
`disabled`	`boolean`	`false`
`prefix-label`	`string`	`''`
`suffix-label`	`string`	`''`
`prefix-icon`	`string`	`''`
`suffix-icon`	`string`	`''`
`value`	`string`	`on`

Events

Event	Source	Notes
`change`	host	Redispatched from the inner native checkbox.

Slots

Slot	Notes
`label`	Optional content above the control. Overrides the `label` prop when present.
`description`	Optional helper content below the control. Overrides the `description` prop when present.
`prefix-label`	Optional rich label content before the switch track. Overrides the `prefix-label` prop when present.
`suffix-label`	Optional rich label content after the switch track. Overrides the `suffix-label` prop when present.
`prefix-icon`	Optional icon/content before the switch track. Overrides the `prefix-icon` prop when present.
`suffix-icon`	Optional icon/content after the switch track. Overrides the `suffix-icon` prop when present.
`error`	Optional validation message below the control. It replaces `description` while the inner control is invalid.

Notes

The public tag is `stellar-switch`, backed by a real native `<input type="checkbox">` inside the component.
`label` and `description` match the rest of the StellarUI field-control family, and `orientation` controls whether the label sits above or inline with the switch.
`prefix-label` and `suffix-label` add optional text beside the switch track; `prefix-icon` and `suffix-icon` render inside their matching label, and matching named slots override prop fallbacks when richer markup is needed.
`required`, `aria-invalid`, and `custom-validity` forward to the inner native checkbox for validation-sensitive flows.
The host exposes `setCustomValidity()`, `checkValidity()`, `reportValidity()`, `validity`, `validationMessage`, and `willValidate`, so app code can use native-like validity APIs on the custom element.
For Datastar, prefer `data-attr:custom-validity="..."` on the custom element host instead of the Pro-only `data-custom-validity` attribute.
`checked`, `disabled`, and `value` mirror native checkbox semantics, while `indeterminate` sets the native property after render.
The host redispatches `change` so outer Datastar listeners can treat it like a normal form control.
The size ramp follows the shared selector sizing so the switch stays close to the checkbox/select control family.