Toggle API

Import

import { UNSTABLE_Toggle } from '@cimpress-ui/react';

Controlled/uncontrolled usage

This component can be used in a controlled or uncontrolled way.

In the controlled way, this component doesn’t maintain its own internal state, and its value is provided by the parent component. Use the controlled way when you need to be able to change the state of this component in other parts of your application.

In the uncontrolled way, this component maintains its own internal state, and can optionally notify the parent component when its internal state changes. Use the uncontrolled way when you don’t need to change the state of this component in other parts of your application.

Preview
Code

I am controlled by React stateI am uncontrolled and unselected by defaultI am uncontrolled and selected by default

import { UNSTABLE_Toggle as Toggle, Stack } from '@cimpress-ui/react';
import { useState } from 'react';

export default function Demo() {
  const [isSelected, setIsSelected] = useState(false);

  return (
    <Stack gap={32}>
      <Toggle isSelected={isSelected} onChange={setIsSelected}>
        I am controlled by React state
      </Toggle>

      <Toggle>I am uncontrolled and unselected by default</Toggle>

      <Toggle defaultSelected>I am uncontrolled and selected by default</Toggle>
    </Stack>
  );
}

Accessibility notes

The toggle state can be changed by pressing Enter or Space, similar to a native HTML checkbox.

Toggle requires a textual label to remain accessible to assistive technologies. See our accessibility guide for more details.

The toggle label must remain the same regardless of the selection state.

API reference

Toggle

Allows users to turn a setting on or off.

See toggle usage guidelines.

ref Ref<HTMLLabelElement>: The ref type for this component.

UNSTABLE_ToggleProps

children StringLikeChildren: The label rendered next to the toggle.
id string: The element's unique identifier. See MDN.
data-cim-style-root boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
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.
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.
name string: The name of the input element, used when submitting an HTML form. See MDN.
autoFocus boolean: Whether the element should receive focus on render.
isDisabled boolean: Whether the input is disabled.
isReadOnly boolean: Whether the input can be selected but not changed by the user.
defaultSelected boolean: Whether the Switch should be selected (uncontrolled).
isSelected boolean: Whether the Switch should be selected (controlled).
onChange (isSelected: boolean) => void: Handler that is called when the Switch's selection state changes.
value string: The value of the input element, used when submitting an HTML form. See MDN.

StyleProps

margin Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.