Inputs@knitui/components

Switch

Switch is a toggle control built on a styled Box track and thumb. It supports controlled and uncontrolled modes, inline labels, on/off track labels, a thumb icon slot, and a Switch.Group for multi-select scenarios.

WebiOSAndroid8 style slots18 own props14 examples

Stories Source Tests Open in Storybook

import { Switch } from "@knitui/components";

Playground

Loading playground…

sizeControls the height, width and thumb dimensions of the track.

disabled

false

withThumbIndicatorShow a coloured dot inside the thumb.

true

labelPositionPosition of the label relative to the track.

label

description

error

offLabel

onLabel

Playground

<Switch
  label="Switch"
  size="sm"
  disabled={false}
  withThumbIndicator
  labelPosition="right"
/>

Examples

Sizes

All seven sizes side by side for a quick visual comparison.

Loading example…

SizesSource Storybook

Shadows

Elevation shadow ladder applied to the track via the inherited shadow prop.

Loading example…

ShadowsSource Storybook

Disabled

Disabled state — the switch is non-interactive and visually dimmed.

Loading example…

DisabledSource Storybook

Track Labels

On/off labels rendered inside the track, behind the thumb.

Loading example…

Track LabelsSource Storybook

Thumb Icon

An icon rendered inside the thumb replaces the default dot indicator.

Loading example…

Thumb IconSource Storybook

Themes

Accent colour comes from the Tamagui theme prop.

Loading example…

ThemesSource Storybook

Label Left

Label placed to the left of the track.

Loading example…

Label LeftSource Storybook

With Description And Error

Description and error slot — rendered below the label when provided.

Loading example…

With Description And ErrorSource Storybook

Controlled

Fully controlled switch — the parent manages checked state via React.useState.

Loading example…

ControlledSource Storybook

Group

Switch.Group manages a set of switches as a multi-select; maxSelectedValues caps the selection.

Loading example…

GroupSource Storybook

Group Read Only

A read-only Switch.Group keeps the current values visible but prevents toggling them.

Loading example…

Group Read OnlySource Storybook

Controlled Group

Controlled Switch.Group — parent tracks the selected values array.

Loading example…

Controlled GroupSource Storybook

Styles

Per-slot styles targets individual parts — here the track, thumb and label.

Loading example…

StylesSource Storybook

Props

Prop	Type	Default	Description
`aria-describedby`	`string \| undefined`	—	Ids of external description elements; merged with description/error ids.
`aria-label`	`string \| undefined`	—	Accessible label when no visible label is provided.
`aria-labelledby`	`string \| undefined`	—	Id of an external label element. Defaults to the visible label id.
`checked`	`boolean \| undefined`	—	Controlled checked state.
`defaultChecked`	`boolean \| undefined`	`false`	Initial checked state for the uncontrolled case.
`description`	`ReactNode`	—	Description rendered below the label.
`disabled` system	`boolean \| undefined`	`false`	Disables the switch.
`error`	`ReactNode`	—	Error rendered below the description (string nodes get the error theme).
`id`	`string \| undefined`	—	Id used to bind the control and label; auto-generated when omitted.
`label`	`ReactNode`	`Switch`	Label content rendered next to the control.
`labelPosition`	`"left" \| "right" \| undefined` left · right	`'right'`	Position of the label relative to the track.
`offLabel`	`ReactNode`	—	Inner label shown in the track when unchecked.
`onChange`	`((checked: boolean) => void) \| undefined`	—	Called with the next checked state. Mirrors Mantine's `onChange` name; the payload is a boolean (not a DOM event) because the kit is cross-platform.
`onCheckedChange`	`((checked: boolean) => void) \| undefined`	—
`onLabel`	`ReactNode`	—	Inner label shown in the track when checked.
`radius` system	`string \| number \| undefined`	—
`rootRef`	`Ref<TamaguiElement> \| undefined`	—	Ref of the root wrapper element.
`shadow` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined`	—
`size` system	`"xs" \| "sm" \| "md" \| "lg" \| "xl" \| "xxs" \| "xxl" \| undefined` xxs · xs · sm · md · lg · xl · xxl	`'sm'`	Controls the height, width and thumb dimensions of the track.
`styles` system	`SlotStyles<SwitchStyles> \| undefined`	—	Uniform per-slot style passthrough — sugar over the composable parts. Own slots: `track` / `thumb` / `thumbIndicator` / `trackLabel`; plus the inherited chrome slots `label` / `description` / `error` / `root` forwarded to the `InlineControl`.
`theme` system	`ThemeName \| null \| undefined`	—	Applies a theme to this element
`thumbIcon`	`ReactNode`	—	Icon rendered inside the thumb.
`value`	`string \| undefined`	—	Value reported to a surrounding `Switch.Group`.
`withThumbIndicator`	`boolean \| undefined`	`true`	Show a coloured dot inside the thumb.

Style slots

Every part of Switch can be styled through the styles prop. Explicit props on the component always win over slot styles.

Slot	Usage
`description`	`styles={{ description: { … } }}`
`error`	`styles={{ error: { … } }}`
`label`	`styles={{ label: { … } }}`
`root`	`styles={{ root: { … } }}`
`thumb`	`styles={{ thumb: { … } }}`
`thumbIndicator`	`styles={{ thumbIndicator: { … } }}`
`track`	`styles={{ track: { … } }}`
`trackLabel`	`styles={{ trackLabel: { … } }}`

Accessibility & DOM props (2)

Prop	Type
`key`	`Key \| null \| undefined`
`ref`	`Ref<TamaguiElement> \| undefined`

Plus 495 inherited style props from Box — the full Tamagui/React Native style surface, including token shorthands like p, mx, bg and c. See Tokens for the scales they accept, or the full list.