React UI
Edit page
Home
Getting Started
Customize
Foundation
Components: UI
Alert Badge Button ButtonGroup Card CheckboxField Modal Radio ScrollView SelectField Table TextArea TextField Toggle
Basic Usage General Guidelines Help Text Label Options States API
Components: Layouts
CSS Helpers
Readme

# Toggle

Toggle switches things on and off.

##
Basic Usage

To implement the Toggle component, you need to import it first:

    import { Toggle } from '@react-ui-org/react-ui';

And use it:

Listen in studio quality
() => { const [studioQuality, setStudioQuality] = React.useState(true) return ( <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} id="my-toggle" label="Listen in studio quality" /> ) }

    () => {  const [studioQuality, setStudioQuality] = React.useState(true)  return (    <Toggle      changeHandler={() => setStudioQuality(!studioQuality)}      checked={studioQuality}      id="my-toggle"      label="Listen in studio quality"    />  )}

See
API for all available options.

## General Guidelines

- Use the toggle only for boolean (true/false) input
  with an immediate effect (without confirmation). To toggle things on or off in forms that require to be submitted by a button, use rather the CheckboxField component.

- Use positive wording for the toggle label, so that it's clear what will happen when the user turns on the toggle. Avoid negations such as “Don't send me any emails” which would mean that the user needs to turn the toggle on in order for something not to happen.

- Only make the Toggle's label invisible when there is another visual clue to guide users through using the input.

- When a short label is not enough, use help texts to guide users before they enter anything.

- Use clear, calm error messages when there's a problem with what they entered.

- The toggle is designed for switching things on and off. Don't use it to switch between two different things that cannot be described as on or off using a single label, eg. different viewing modes. In such cases, consider using the ButtonGroup component.

## Help Text

You may provide an additional help text to clarify what will be the impact of turning the toggle on or off.

Listen in studio quality
Unrivaled audio quality. Uses the MQA audio format. Transfers a lot of data.
() => { const [studioQuality, setStudioQuality] = React.useState(true) return ( <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} description={ 'Unrivaled audio quality. Uses the MQA audio format. ' + 'Transfers a lot of data.' } id="my-toggle-with-helper-text" label="Listen in studio quality" /> ) }

    () => {  const [studioQuality, setStudioQuality] = React.useState(true)  return (    <Toggle      changeHandler={() => setStudioQuality(!studioQuality)}      checked={studioQuality}      description={        'Unrivaled audio quality. Uses the MQA audio format. ' +        'Transfers a lot of data.'      }      id="my-toggle-with-helper-text"      label="Listen in studio quality"    />  )}

## Label Options

In some cases, it may be convenient to visually hide the toggle label. The label remains accessible to assistive technologies.

You cannot see this
() => { const [studioQuality, setStudioQuality] = React.useState(true) return ( <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} id="my-toggle-with-invisible-label" isLabelVisible={false} label="You cannot see this" /> ) }

    () => {  const [studioQuality, setStudioQuality] = React.useState(true)  return (    <Toggle      changeHandler={() => setStudioQuality(!studioQuality)}      checked={studioQuality}      id="my-toggle-with-invisible-label"      isLabelVisible={false}      label="You cannot see this"    />  )}

It's also possible to display the label before the input:

Listen in studio quality
() => { const [studioQuality, setStudioQuality] = React.useState(true) return ( <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} id="my-toggle-with-label-before-input" label="Listen in studio quality" labelPosition="before" /> ) }

    () => {  const [studioQuality, setStudioQuality] = React.useState(true)  return (    <Toggle      changeHandler={() => setStudioQuality(!studioQuality)}      checked={studioQuality}      id="my-toggle-with-label-before-input"      label="Listen in studio quality"      labelPosition="before"    />  )}

## States

### Validation States

Validation states visually present the result of validation of the input. You should always provide a help text for states other than valid so users know what happened and what action they should take or what options they have.

Listen in studio quality
Listen in studio quality
Looks like you are connected over cellular network. Please make sure you know what you are doing.
Listen in studio quality
Please upgrade your plan to make this option available.
() => { const [studioQuality, setStudioQuality] = React.useState(true) return ( <> <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} id="my-toggle-valid" label="Listen in studio quality" validationState="valid" /> <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} description={ 'Looks like you are connected over cellular network. ' + 'Please make sure you know what you are doing.' } id="my-toggle-warning" label="Listen in studio quality" validationState="warning" /> <Toggle changeHandler={() => setStudioQuality(!studioQuality)} checked={studioQuality} error="Please upgrade your plan to make this option available." id="my-toggle-invalid" label="Listen in studio quality" validationState="invalid" /> </> ) }

    () => {  const [studioQuality, setStudioQuality] = React.useState(true)  return (    <>      <Toggle        changeHandler={() => setStudioQuality(!studioQuality)}        checked={studioQuality}        id="my-toggle-valid"        label="Listen in studio quality"        validationState="valid"      />      <Toggle        changeHandler={() => setStudioQuality(!studioQuality)}        checked={studioQuality}        description={          'Looks like you are connected over cellular network. ' +          'Please make sure you know what you are doing.'        }        id="my-toggle-warning"        label="Listen in studio quality"        validationState="warning"      />      <Toggle        changeHandler={() => setStudioQuality(!studioQuality)}        checked={studioQuality}        error="Please upgrade your plan to make this option available."        id="my-toggle-invalid"        label="Listen in studio quality"        validationState="invalid"      />    </>  )}

### Disabled State

Disabled state makes the input unavailable.

Disabled toggle
Disabled toggle, checked
<Toggle label="Disabled toggle" id="my-toggle-disabled" disabled /> <Toggle label="Disabled toggle, checked" id="my-toggle-checked-disabled" disabled checked />

    <Toggle label="Disabled toggle" id="my-toggle-disabled" disabled /><Toggle  label="Disabled toggle, checked"  id="my-toggle-checked-disabled"  disabled  checked/>

## API

In addition to the options below, you can add any custom attributes that do not interfere with the API, and they will be passed to the
`input` HTML element. This is useful mainly to improve component's accessibility.

changeHandler
func
null
checked
bool
false
description
string
null
disabled
bool
false
error
string
null
forwardedRef
Function │ { "current": "any" }
undefined
id
string
required
inFormLayout
bool
false
isLabelVisible
bool
true
label
string
required
labelPosition
'before' │ 'after'
'after'
layout
'horizontal' │ 'vertical'
'vertical'
required
bool
false
validationState
'invalid' │ 'valid' │ 'warning'
null
value
string │ number
undefined

Next: CTA →