Skip Navigation
React Magma

Toggle

Toggles (also called Switches) are form elements used to set a single item either an on or off value.

See also: Checkboxes and Radio Buttons.

Basic Usage

The label/toggle association will be handled via the passed in id if one is supplied or via an auto-generated id if not supplied.

Toggles can either be controlled or uncontrolled. If you pass in a checked prop, it is a controlled input. That means that to change the toggle's state, you must updated the checked prop's value. If you do not want to have your toggle be in a controlled state, but need the initial checked value to be set, pass in the defaultChecked prop with the value you would like on initial render.

import React from 'react';


import { Toggle, FormGroup } from 'react-magma-dom';


export function Example() {
  const [checked, updateChecked] = React.useState<boolean>(false);


  function handleUpdateChecked() {
    updateChecked(!checked);
  }


  return (
    <FormGroup labelText="Toggle one or more">
      <Toggle defaultChecked labelText="Uncontrolled Toggle" />
      <Toggle
        checked={checked}
        labelText="Controlled toggle"
        onChange={handleUpdateChecked}
      />
    </FormGroup>
  );
}

Disabled

import React from 'react';


import { Toggle } from 'react-magma-dom';


export function Example() {
  return (
    <>
      <Toggle disabled labelText="Disabled toggle" />
      <Toggle disabled checked labelText="Disabled toggle on" />
    </>
  );
}

Error Message

An errorMessage can also be supplied to an toggle to indicate the selection is invalid.

The required attribute can be used on a toggle if that field is required.

import React from 'react';


import { Toggle } from 'react-magma-dom';


export function Example() {
  const [hasError, setHasError] = React.useState(true);


  const message = hasError ? 'You must turn permissions on' : null;


  function handleChange(e) {
    setHasError(!e.target.checked);
  }


  return (
    <Toggle
      errorMessage={message}
      labelText="Enable Permissions"
      onChange={handleChange}
      required
    />
  );
}

Text Position

Use the optional prop textPosition to position the label text on either side of the toggle switch. The textPosition property takes the values left and right. The default value is left.

import React from 'react';


import { Toggle } from 'react-magma-dom';


export function Example() {
  return (
    <>
      <Toggle labelText="Text left" />
      <Toggle labelText="Text right" textPosition="right" />
    </>
  );
}

Visually Hidden Label

Adding the isTextVisuallyHidden prop will make the label text available to screen readers, but will hide it visually.

Use caution when using the isTextVisuallyHidden prop; it should only be used in rare circumstances when the purpose of the toggle is conveyed in another way. While screen readers will announce the label when the toggle gains focus, it is still best to have a visual label. This is especially helpful for individuals with cognitive disabilities and users who have fine motor control limitations.
import React from 'react';


import { Toggle } from 'react-magma-dom';


export function Example() {
  return <Toggle labelText="Label is hidden" isTextVisuallyHidden />;
}

Custom Styles

Custom styles can be passed into both the Toggle component. The containerStyle property will apply to the container. Additional labelStyle, trackStyle and thumbStyle properties are available to style the respective elements. Please use discretion when adding custom styles.

import React from 'react';


import { Toggle } from 'react-magma-dom';


export function Example() {
  return (
    <Toggle
      containerStyle={{ border: '1px dotted purple', width: '100%' }}
      labelStyle={{ fontStyle: 'italic', flexGrow: '1' }}
      labelText="Custom styles"
      thumbStyle={{
        background: 'yellow',
        border: '1px solid orange',
        boxShadow: '0 0 0',
      }}
      trackStyle={{ borderRadius: '5px', height: '24px' }}
    />
  );
}

Inverse

import React from 'react';


import { Toggle, Card, CardBody } from 'react-magma-dom';


export function Example() {
  return (
    <Card isInverse>
      <CardBody>
        <Toggle isInverse labelText="Inverse toggle" />
        <Toggle isInverse disabled checked labelText="Inverse disabled" />
      </CardBody>
    </Card>
  );
}

Testing

Passing in the testId prop will add the data-testid attribute to the input element for easier querying in tests.

<Toggle labelText="Toggle label" testId="toggle-testid" />

Toggle Props

This component uses forwardRef. The ref is applied to the input element.

All of the standard input attributes can be provided as props and will be applied to the input element that gets rendered.

checked

Description

If true, element is checked (i.e. selected)

Type

boolean

Default

false

containerStyle

Description

Style properties for the component container element

Type

CSSProperties

Default

-

defaultChecked

Description

If true, checkbox is checked on first render

Type

boolean

Default

false

errorMessage

Description

Content of the error message for toggle. If a value is provided, the component will be styled as an error state and the error message will display.

Type

React.ReactNode

Default

-

isInverse

Description

If true, the component will have inverse styling to better appear on a dark background

Type

boolean

Default

false

isTextVisuallyHidden

Description

If true, label text will be hidden visually, but will still be read by assistive technology

Type

boolean

Default

false

labelStyle

Description

Style properties for the label element

Type

CSSProperties

Default

-

labelText

Required

Description

Content for label; can be a node or a string

Type

React.ReactNode

Default

-

textPosition

Description

Whether the label appears to the left of the right of the toggle switch

Type

enum, one of:
ToggleTextPosition.left
ToggleTextPosition.right

Default

ToggleTextPosition.left

thumbStyle

Description

Style properties for the part of the component that slides back and forth on the track

Type

CSSProperties

Default

-

trackStyle

Description

Style properties for track on which the toggle thumb slides

Type

CSSProperties

Default

-

On this page

Deploys by Netlify