Switch

Copy for LLM

Switches allow users to toggle between two states, off and on.

Import

import { Switch } from "@cfa/react-core";

Live Editor

Examples

Description

Use the description prop to add a description to the switch. The description will be displayed below the switch.

AutoFocus

Use the autoFocus prop to automatically focus the switch when it is mounted.

Readonly

The isReadOnly prop makes the switch read-only, preventing user interaction.

Disabled

The isDisabled prop disables the switch, preventing user interaction.

Default Selected

Use the defaultSelected prop to set the initial state of the switch. The switch will be checked by default.

Controlled

To use the Switch in a controlled state, you can use the combination of isSelected which is a boolean and onChange which accepts a function.

Label Position

The labelPosition prop allows you to change the position of the label. The default is right.

Native HTML Forms

The Switch component can be used in native HTML forms. The name prop is required for the switch to be submitted with the form.

Props

Visit the Documentation Site for the full list of props.

Switch

Name	Type	Default	Description
children	`ReactNode`	-	The label of the switch.
description	`string`	-	Helper text for the switch.
inputRef	`RefObject<HTMLInputElement>`	-	React 19 only
labelPosition	`"left" \| "right" \| "top"`	-	-
ref	`Ref<HTMLLabelElement>`	-	React 19 only
aria-controls	`string`	-	Identifies the element (or elements) whose contents or presence are controlled by the current element.
aria-describedby	`string`	-	Identifies the element (or elements) that describes the object.
aria-details	`string`	-	Identifies the element (or elements) that provide a detailed, extended description for the object.
aria-label	`string`	-	Defines a string value that labels the current element.
aria-labelledby	`string`	-	Identifies the element (or elements) that labels the current element.
autoFocus	`boolean`	-	Whether the element should receive focus on render.
className	`ClassNameOrFunction<SwitchRenderProps>`	`'react-aria-Switch'`	The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state.
defaultSelected	`boolean`	-	Whether the Switch should be selected (uncontrolled).
dir	`string`	-	-
excludeFromTabOrder	`boolean`	-	Whether to exclude the element from the sequential tab order. If true, the element will not be focusable via the keyboard by tabbing. This should be avoided except in rare scenarios where an alternative means of accessing the element or its functionality via the keyboard is available.
form	`string`	-	The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form).
hidden	`boolean`	-	-
id	`string`	-	The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id).
inert	`boolean`	-	-
isDisabled	`boolean`	-	Whether the input is disabled.
isReadOnly	`boolean`	-	Whether the input can be selected but not changed by the user.
isSelected	`boolean`	-	Whether the Switch should be selected (controlled).
lang	`string`	-	-
name	`string`	-	The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname).
onAnimationEnd	`AnimationEventHandler<HTMLLabelElement>`	-	-
onAnimationEndCapture	`AnimationEventHandler<HTMLLabelElement>`	-	-
onAnimationIteration	`AnimationEventHandler<HTMLLabelElement>`	-	-
onAnimationIterationCapture	`AnimationEventHandler<HTMLLabelElement>`	-	-
onAnimationStart	`AnimationEventHandler<HTMLLabelElement>`	-	-
onAnimationStartCapture	`AnimationEventHandler<HTMLLabelElement>`	-	-
onAuxClick	`MouseEventHandler<HTMLLabelElement>`	-	-
onAuxClickCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onBlur	`(e: FocusEvent<Element, Element>) => void`	-	Handler that is called when the element loses focus.
onChange	`(isSelected: boolean) => void`	-	Handler that is called when the Switch's selection state changes.
onClickCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onContextMenu	`MouseEventHandler<HTMLLabelElement>`	-	-
onContextMenuCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onDoubleClick	`MouseEventHandler<HTMLLabelElement>`	-	-
onDoubleClickCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onFocus	`(e: FocusEvent<Element, Element>) => void`	-	Handler that is called when the element receives focus.
onFocusChange	`(isFocused: boolean) => void`	-	Handler that is called when the element's focus status changes.
onGotPointerCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onGotPointerCaptureCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onHoverChange	`(isHovering: boolean) => void`	-	Handler that is called when the hover state changes.
onHoverEnd	`(e: HoverEvent) => void`	-	Handler that is called when a hover interaction ends.
onHoverStart	`(e: HoverEvent) => void`	-	Handler that is called when a hover interaction starts.
onKeyDown	`(e: KeyboardEvent) => void`	-	Handler that is called when a key is pressed.
onKeyUp	`(e: KeyboardEvent) => void`	-	Handler that is called when a key is released.
onLostPointerCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onLostPointerCaptureCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onMouseDown	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseDownCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseEnter	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseLeave	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseMove	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseMoveCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseOut	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseOutCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseOver	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseOverCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseUp	`MouseEventHandler<HTMLLabelElement>`	-	-
onMouseUpCapture	`MouseEventHandler<HTMLLabelElement>`	-	-
onPointerCancel	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerCancelCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerDown	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerDownCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerEnter	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerLeave	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerMove	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerMoveCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerOut	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerOutCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerOver	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerOverCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerUp	`PointerEventHandler<HTMLLabelElement>`	-	-
onPointerUpCapture	`PointerEventHandler<HTMLLabelElement>`	-	-
onScroll	`UIEventHandler<HTMLLabelElement>`	-	-
onScrollCapture	`UIEventHandler<HTMLLabelElement>`	-	-
onTouchCancel	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchCancelCapture	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchEnd	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchEndCapture	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchMove	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchMoveCapture	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchStart	`TouchEventHandler<HTMLLabelElement>`	-	-
onTouchStartCapture	`TouchEventHandler<HTMLLabelElement>`	-	-
onTransitionCancel	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionCancelCapture	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionEnd	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionEndCapture	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionRun	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionRunCapture	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionStart	`TransitionEventHandler<HTMLLabelElement>`	-	-
onTransitionStartCapture	`TransitionEventHandler<HTMLLabelElement>`	-	-
onWheel	`WheelEventHandler<HTMLLabelElement>`	-	-
onWheelCapture	`WheelEventHandler<HTMLLabelElement>`	-	-
render	`DOMRenderFunction<"label", SwitchRenderProps>`	-	Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: * You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). * Only a single root DOM element can be rendered (no fragments). * You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate.
slot	`string`	-	A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent.
style	`StyleOrFunction<SwitchRenderProps>`	-	The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state.
translate	`"yes" \| "no"`	-	-
value	`string`	-	The value of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefvalue).