Switch

A switch allows the user to immediately turn an option on or off.

Anatomy

1. Label - a short name that lets the user know what the switch will turn on or off.
2. Description (optional) - a description that can be used to add clarity to the role of the switch.
3. Control - an indicator that lets the user know the current state of the switch.

Usage

• When a user toggles a switch, its corresponding action takes effect right away.
• A switch has two mutually exclusive states—on and off.

Do

• Do use a switch to mimic a physical on/off switch in the interface.
• Do allow users to select the switch by clicking the control or its text label.

Don't

• Don’t use the words "on/off" in the switch’s text label. The option that the switch controls should be clear from its label. A tooltip/title attribute may be added to convey the on/off state.
• Don’t use a switch if the option is part of a larger flow, with a final confirmation step or Submit button. Use a checkbox instead.
• Don’t use a switch if users can select multiple options from a list. Use checkboxes instead.

React API

import { Switch } from '@wwnds/react';

Switch

Live Editor

<Switch label="Switch" />

Result

Loading...

Name	Description	Type
label (required)	The name of the Switch. Required.	ReactNode
children	Children are set inside the Switch control. Default is 'ON' when checked and OFF when unchecked. Disable default with displayDefault={false}.	ReactNode
tipped	Indicates that the label should be rendered as a tooltip.	boolean
checked	The switch's initial "on" state.	boolean
onToggle	A function to call when the switch is toggled.	((checked: boolean) => void)
displayDefault	Indicates whether the default control text should be used when no children are provided. "ON" when checked=true and "OFF" when checked=false.	boolean
baseName	The base class name according to BEM conventions.	string
tooltipProps	Tooltip props that should be included when the switch's label is rendered as a tooltip.	Partial<TooltipCoreProps>
description	An optional description. Use this in place of placeholder text or as help text for your field control.	ReactNode
labelClass	A className for the label element, which will be a <label> if htmlFor is included and a <div> otherwise.	string
descriptionClass	A className for the description <div>.	string
labelId	An id for the label element.	string
descriptionId	An id for the description <div>.	string
icon	An icon to include in the button.	IconVariant | SVGIcon
color	The button's color, restricted to design system colors, excluding disabled (prefer the disabled prop). Note that an undefined color will result in the "primary" color being used.	"base" | "warning" | SystemColors | "primary" | "error" | "success"
iconClass	The className for the Button's icon, if one exists.	string
variant	Button variant conveys the button's level of visual emphasis.	"solid" | "outline" | "ghost"
iconRight	Indicates whether the icon should be to the right of the text. By default, the icon is to the left of the text.	boolean
iconOnly	Indicates whether the button's contents should only be the icon. When true, the button's text is still required but will be used as the icon's aria-label. If no icon is specified, this prop has no effect.	boolean
buttonRef	A reference to the inner <button> element.	Ref<HTMLButtonElement>
textClass	The className for the Button's text, which will be placed in a <span>	string
active	Whether the button is currently depressed. Polyfill for :active on keydown.	boolean
activeClass	A class to convey :active.	string