Switch

Switch in Storybook

Examples

Check out the Usage section for details about how to design a switch properly, and the different configuration options we provide.

Basic example

A switch is a component that a user can use to change between an on and off state.

<Switch label="Switch" />

OnChange example

You can set a callback function to run when a user changes a switch's state.

<Switch
  label="Switch"
  OnChange={(event, value) =>
    console.log('Switch toggled. The value is now', value)
  }
/>

Usage

Overview

Switch is a component that alternates between two possible states: active and inactive. The switch is used for global options, such as in settings pages when the user needs to turn something on or off.

For a detailed guide on when to use this component, explore the following UI component decision tree.

When to use

To toggle an application state between two options such as on/off and active/inactive. Ensure that switches take effect immediately and don't require additional action.

When not to use

• For a true/false selection within a form. Instead, use the radio group or toggle button group.
• If pressing a button is required to apply a setting. Instead, use checkbox.

Do use the radio group or toggle button group for a true/false selection within a form.

Don't use the switch as part of a form. This violates the rule that anything changed by the switch must take immediate effect.

Formatting

Anatomy

The switch consists of the following elements:

1. Label: concise text that describes the specific function or setting the switch controls.
2. Track: horizontal path along which users slide the switch handle.
3. Handle: movable element users slide along the track to toggle the switch state.

Label placement

The label for the switch can appear at the top (default and recommended) or on the left of the input itself.

Content

General writing guidelines

• Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
• Use present tense verbs and active voice in most situations.
• Use common contractions to lend your copy a more natural and informal tone.
• Use plain language. Avoid unnecessary jargon and complex language.
• Keep words and sentences short.

Label text

Labels must clearly communicate which function or setting the switch controls, such as "Autosave".

Do keep the label short and direct. The label describes what the control does when the switch is on.

Don't add the text “on” or “off” into the switch. The font size is too small to be accessible.

Help text

Switches are a well-known selection control and generally don't require additional explanation. That is, you don't need to instruct users to "toggle" the switch.

Use permanent help text when the information is essential for understanding the switch's function and must always be visible.

Do use help text for essential context that must always remain visible.

Don't use help text to prompt the user to toggle the selection control.

Behaviors

States

The switch has two main states: deselected and selected.

Visual	State	Description
	Deselected	Indicates "off" state.
	Selected	Indicates "on" state.

In addition to the deselected and selected states, switches also have states for enabled, hover, active, focus, and disabled.

Visual	State	Description
	Enabled	Communicates to the user that the element is enabled for interaction (default state).
	Hover	Indicates that the user has placed a cursor over the element.
	Active	Indicates that the user is clicking or tapping the element.
	Focus	Provides feedback indicating the user has highlighted the element, typically using an input method such as a keyboard or voice. The focus state can be used with all other states (including Disabled).
	Disabled	Communicates to the user that the element is disabled and not interactive. The element is greyed out.

Interactions

Mouse

A user interacts with a switch component by clicking on it with a mouse to toggle between its on and off states. To indicate the new state, the track changes color and the handle changes position.

Keyboard

The switch component is keyboard-focusable. The Space key activates and deactivates the switch.

Screenreader

The switch is of type 'input' and also includes the aria role of 'switch'. It derives its accessible name from the value of the text label & includes this name as part of an aria-label attribute. Changing the value of the label in Storybook also changes the aria-label value. The aria-checked value toggles from 'true' to 'false' depending on the state of the element; this change is voiced by screen readers as 'on' and 'off' respectively.

Accessibility

The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.

This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.

When using this component within your application, ensure that the switch label text is meaningful and understandable.

Code

<Switch label="Switch" />

Import statement

import { Switch } from '@jutro/components/new';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

labelrequired

Type

IntlMessageShape

Description

The label associated with the switch field, also passed as a default value to 'aria-label'.

checked

Type

boolean

Description

State of the switch. If set to true, the switch is checked. Takes precedence over initialChecked. If this prop is passed, the component works in controlled mode and its value will change only if this prop changes.

className

Type

string

Description

CSS class name for this component.

disabled

Type

boolean

Description

If set to true, the component is rendered in a disabled state.

hideLabel

Type

boolean

Description

If set to true, the label is not visible.

initialChecked

Type

boolean

Description

Initial checked state of the switch. If set to true, the switch is checked. If the checked prop is specified along with this prop, this prop is discarded.

labelPosition

Type

'top' | 'left'

Description

Allows to select the label position.

Default value

'top'

onChange

Type

function (React.ChangeEvent<HTMLInputElement>, boolean)

Description

Callback invoked when component value is changed.

Hooks

No hooks are available for Switch.

Translation keys

There are no translations for Switch.

For information on how to manage translations, see our section about Internationalization.

Escape hatches

For more information, see our documentation about escape hatches.

10.5.0

New @jutro/components/new/Switch component introduced.

You can still import the old SwitchField component from @jutro/components/SwitchField, but you will get a warning that it is deprecated when doing so.