Switch
Component that switches between two states.
The <Switch> component allows the users to select between two states, e.g. on and off.
It consists of a visual selection indicator and a label.
Users may click or touch a Switch to toggle the state, or use the tab key to navigate to it and the space key to toggle it.
Anatomy
The styles are separated into some parts (container, label, thumb, track) that you can style in a custom variant.
Appearance
The appearance of a component can be customized using the variant and size props. These props adjust the visual style and dimensions of the component, available values are based on the active theme.
Variant
Size
The selected theme does not has any options for "variant" and "size".
| Property | Type | Description |
|---|---|---|
variant | - | The available variants of this component. |
size | - | The available sizes of this component. |
Usage
Switches are best used to adjust settings and other standalone options. They make a binary selection, like on and off or true and false.
The effects of a switch should start immediately, without needing to save.
Do
Immediately activate or deactivate something.
Don't
Avoid using a switch to select multiple options that require people to save. Switches should be immediate.
Don't
Avoid using switches to toggle between opposing options.
Props
Did you know? You can explore, test, and customize props live in Marigold's storybook. Watch the effects they have in real-time!
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.
defaultSelected?boolean;
Whether the Switch should be selected (uncontrolled).
dir?string;
disabled?boolean;
Disables the switch.
Defaults to:
"false"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.hidden?boolean;
id?string;
The element's unique identifier. See MDN.
inert?boolean;
inputRef?RefObject<HTMLInputElement | null>;
A ref for the HTML input element.
label?ReactNode;
Set the label of the switch.
lang?string;
name?string;
The name of the input element, used when submitting an HTML form. See MDN.
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>;
readOnly?boolean;
Set the switch to read-only.
Defaults to:
"false"ref?Ref<HTMLLabelElement>;
Allows getting a ref to the component instance.
Once the component unmounts, React will set
ref.current to null
(or call the ref with null if you passed a callback ref).
@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}selected?boolean;
With this prop you can set the switch selected.
Defaults to:
"false"translate?"yes" | "no";
value?string;
The value of the input element, used when submitting an HTML form. See MDN.
width?WidthProp;
Sets the width of the field. You can see allowed tokens here: https://tailwindcss.com/docs/width
Defaults to:
"full"Alternative components
Alternative selection controls can be used to enter decisions or declare preferences such as settings or dialogs.
Last update: October 25, 2024