Switch

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.

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 Jutro switch component adheres to the following criteria for color and zoom accessibility:

• Color: Textual elements have a contrast ratio above 4.5:1 against their background, as per WCAG 2.0 AA requirements.
• Zoom: All content is visible and functional up to and including a zoom factor of 200%.

This component has been validated to meet the WCAG 2.0 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance. 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

bool

Description

State of the switch. If true, the switch is checked, if false it is unchecked. 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 passed to the root element of the component.

disabled​

Type

bool

Description

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

hideLabel​

Type

bool

Description

If true, the label is not visible.

initialChecked​

Type

bool

Description

Initial checked state of the switch. If true, the switch is checked, if false it is unchecked. 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.

onChange​

Type

func

Description

Callback invoked when the switch 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 Switch component from @jutro/components/Switch, but you will get a warning that it is deprecated when doing so.