Switch

Switches allow users to turn an individual option on or off. They are usually used to activate or deactivate a specific setting.

install	`yarn add @react-spectrum/switch`
version	3.0.0-rc.1
usage	`import {Switch} from '@react-spectrum/switch'`

View guidelines

Spectrum

Example#

<Switch>Switch it up</Switch>

Content#

Switches accept children, which are rendered as the label.

Switches are best used for communicating activation (e.g., on/off states), while checkboxes are best used for communicating selection (e.g. multiple table rows). Switches, unlike checkboxes, can't have an error state.

Accessibility#

In certain cases a visible label isn't needed. For example, a Switch located at the top of a panel which toggles the panels options on or off. If a visible label isn't specified, an aria-label must be provided to the Switch for accessibility. If the field is labeled by a separate element, an aria-labelledby prop must be provided using the id of the labeling element instead.

<Switch aria-label="Activate Setting" />

Internationalization#

To internationalize a Switch, a localized label should be passed to the children or aria-label prop. For languages that are read right to left (e.g. Hebrew and Arabic), the layout of the switch is flipped.

Value#

Switches are not selected by default. The defaultSelected prop can be used to set the default state (uncontrolled). Alternatively, the isSelected prop can be used to make the selected state controlled.

<Switch defaultSelected>Uncontrolled</Switch>
<Switch isSelected>Controlled</Switch>

Events#

Switches accept a user defined onChange prop, triggered whenever the Switch is pressed. The example below uses onChange to alert the user to changes in state.

function Example() {
  let [selected, setSelection] = React.useState('false');

  let toggle = (value) => {
    value ? setSelection('true') : setSelection('false');
  }

  return (
    <div>
      <div> The Switch is on: {selected} </div>
      <Switch onChange={toggle}>
        Switch Label
      </Switch>
    </div>
  );
 }

Props#

Name	Type	Default	Description
`isEmphasized`	`boolean`	`"false"`	By default, switches are not emphasized (gray). This prop sets the emphasized style (blue) which provides visual prominence.
`UNSAFE_className`	`string`	—
`UNSAFE_style`	`CSSProperties`	—

Layout

Name	Type	Default	Description
`flex`	`string \| number \| boolean`	—
`flexGrow`	`number`	—
`flexShrink`	`number`	—
`flexBasis`	`number \| string`	—
`alignSelf`	`'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'stretch'`	—
`justifySelf`	`'auto' \| 'normal' \| 'start' \| 'end' \| 'flex-start' \| 'flex-end' \| 'self-start' \| 'self-end' \| 'center' \| 'left' \| 'right' \| 'stretch'`	—
`flexOrder`	`number`	—
`gridArea`	`string`	—
`gridColumn`	`string`	—
`gridRow`	`string`	—
`gridColumnStart`	`string`	—
`gridColumnEnd`	`string`	—
`gridRowStart`	`string`	—
`gridRowEnd`	`string`	—
`slot`	`string`	—

Spacing

Name	Type	Default	Description
`margin`	`DimensionValue`	—
`marginTop`	`DimensionValue`	—
`marginLeft`	`DimensionValue`	—
`marginRight`	`DimensionValue`	—
`marginBottom`	`DimensionValue`	—
`marginStart`	`DimensionValue`	—
`marginEnd`	`DimensionValue`	—
`marginX`	`DimensionValue`	—
`marginY`	`DimensionValue`	—

Sizing

Name	Type	Default	Description
`width`	`DimensionValue`	—
`minWidth`	`DimensionValue`	—
`maxWidth`	`DimensionValue`	—
`height`	`DimensionValue`	—
`minHeight`	`DimensionValue`	—
`maxHeight`	`DimensionValue`	—

Positioning

Name	Type	Default	Description
`position`	`'static' \| 'relative' \| 'absolute' \| 'fixed' \| 'sticky'`	—
`top`	`DimensionValue`	—
`bottom`	`DimensionValue`	—
`left`	`DimensionValue`	—
`right`	`DimensionValue`	—
`start`	`DimensionValue`	—
`end`	`DimensionValue`	—
`zIndex`	`number`	—
`isHidden`	`boolean`	—

Accessibility

Name	Type	Default	Description
`role`	`string`	—
`id`	`string`	—
`tabIndex`	`number`	—
`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-controls`	`string`	—	Identifies the element (or elements) whose contents or presence are controlled by the current element.
`aria-owns`	`string`	—	Identifies an element (or elements) in order to define a visual, functional, or contextual parent/child relationship between DOM elements where the DOM hierarchy cannot be used to represent the relationship.
`aria-hidden`	`boolean \| 'false' \| 'true'`	—	Indicates that the element is perceivable but disabled, so it is not editable or otherwise operable.

'size-0'
  | 'size-10'
  | 'size-25'
  | 'size-40'
  | 'size-50'
  | 'size-65'
  | 'size-75'
  | 'size-85'
  | 'size-100'
  | 'size-115'
  | 'size-125'
  | 'size-130'
  | 'size-150'
  | 'size-160'
  | 'size-175'
  | 'size-200'
  | 'size-225'
  | 'size-250'
  | 'size-300'
  | 'size-350'
  | 'size-400'
  | 'size-450'
  | 'size-500'
  | 'size-550'
  | 'size-600'
  | 'size-675'
  | 'size-700'
  | 'size-800'
  | 'size-900'
  | 'size-1000'
  | 'size-1200'
  | 'size-1250'
  | 'size-1600'
  | 'size-1700'
  | 'size-2000'
  | 'size-2400'
  | 'size-3000'
  | 'size-3400'
  | 'size-3600'
  | 'size-4600'
  | 'size-5000'
  | 'size-6000'
  | 'static-size-0'
  | 'static-size-10'
  | 'static-size-25'
  | 'static-size-50'
  | 'static-size-40'
  | 'static-size-65'
  | 'static-size-100'
  | 'static-size-115'
  | 'static-size-125'
  | 'static-size-150'
  | 'static-size-175'
  | 'static-size-200'
  | 'static-size-225'
  | 'static-size-250'
  | 'static-size-300'
  | 'static-size-400'
  | 'static-size-450'
  | 'static-size-500'
  | 'static-size-550'
  | 'static-size-600'
  | 'static-size-700'
  | 'static-size-800'
  | 'static-size-900'
  | 'static-size-1000'
  | 'static-size-1200'
  | 'static-size-1700'
  | 'static-size-2400'
  | 'static-size-2600'
  | 'static-size-3400'
  | 'static-size-3600'
  | 'static-size-4600'
  | 'static-size-5000'
  | 'static-size-6000'
  | 'single-line-height'
  | 'single-line-width'
  | string
  | number

Visual Options#

isDisabled#

View guidelines

<Switch isDisabled>Switch Label</Switch>

isEmphasized#

View guidelines

<Switch isEmphasized>Switch Label</Switch>

isReadOnly#

<Switch isReadOnly isSelected>Switch Label</Switch>