FormToggle Edit
FormToggle switches a single setting on or off.
Table of contents Table of contents
Design guidelines Design guidelines
Usage Usage
When to use toggles When to use toggles
Use toggles when you want users to:
- Switch a single option on or off.
- Immediately activate or deactivate something.
Do
Use toggles to switch an option on or off.
Don’t
Don’t use radio buttons for settings that toggle on and off.
Toggles are preferred when the user is not expecting to submit data, as is the case with checkboxes and radio buttons.
State State
When the user slides a toggle thumb (1) to the other side of the track (2) and the state of the toggle changes, it’s been successfully toggled.
Text label Text label
Toggles should have clear inline labels so users know exactly what option the toggle controls, and whether the option is enabled or disabled.
Do not include any text (e.g. “on” or “off”) within the toggle element itself. The toggle alone should be sufficient to communicate the state.
Behavior Behavior
When a user switches a toggle, its corresponding action takes effect immediately.
Development guidelines Development guidelines
Usage Usage
import { FormToggle } from '@wordpress/components'; import { useState } from '@wordpress/element'; const MyFormToggle = () => { const [ isChecked, setChecked ] = useState( true ); <FormToggle checked={ checked } onChange={ () => setChecked( ( state ) => ! state ) } /> };
Props Props
The component accepts the following props:
checked checked
If checked is true the toggle will be checked. If checked is false the toggle will be unchecked.
If no value is passed the toggle will be unchecked.
- Type:
Boolean
- Required: No
disabled disabled
If disabled is true the toggle will be disabled and apply the appropriate styles.
- Type:
Boolean
- Required: No
onChange onChange
A function that receives the checked state (boolean) as input.
- Type:
function
- Required: Yes
Related components Related components
- To select one option from a set, and you want to show them all the available options at once, use the
Radio
component. - To select one or more items from a set, use the
CheckboxControl
component. - To display a toggle with label and help text, use the
ToggleControl
component.