Switch Toggle
A SwitchToggle is a control that enables a user to toggle a setting on or off. It should have an immediate and visible effect, and is designed to function independently or in a group of related controls. It will always represent a binary choice - on or off - with its function described clearly via a label and optional help text.
Installation
npm install @nib/switch-toggle
Note: You will also need to install the following peerDependencies:
Usage
import {SwitchToggle} from '@nib/switch-toggle';
Interactive demo
<SwitchToggle label="Push notifications" help="Turn on to receive many many notifications." />
Props
| Prop | Type | Default | Description |
|---|---|---|---|
label (required) | string | The label for the switch toggle. | |
id | string | The unique identifier for the switch toggle. | |
help | string | Optional help text to describe the purpose of the switch toggle. | |
inline | boolean | false | If true, the switch toggle will be displayed inline with other elements. |
alignIndicator | 'start' | 'end' | end | Determines the alignment of the indicator within the switch toggle. |
bgFill | boolean | true | If true, applies a background fill to the switch toggle. |
showStateIcons | boolean | true | If true, displays state icons within the switch toggle. |
defaultChecked | boolean | false | Determines whether the switch toggle is checked by default. |
checked | boolean | Controls the checked state of the switch toggle (for controlled usage). | |
onChange | function | Callback function invoked when the checked state changes. | |
gap | ResponsiveSpaceProp | {xs: 2, mini: 4} | The gap between the label and the switch toggle. A size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of 1...10 values. |
padding | ResponsiveSpaceProp | 4 | The padding on the outer wrapper around the switch toggle and label component. A size from our spacing scale. Can be made responsive by passing an object of breakpoints. Value(s) must be one of 1...10 values. |
disabled | boolean | false | If true, the switch toggle will be disabled and non-interactive. |
Considerations
When to use
The SwitchToggle is designed for on-page actions. Interacting with the Toggle should have an immediate effect - it should not be used in a form context where a "Submit" button is required to enact the selected changes. It toggles between two mutually-exclusive states - on and off.
If the desired action for a SwitchToggle needs to be validated against other settings or otherwise requires a "Next" or "Submit" button, the Checkbox (or Checkbox Group) should be used instead.
Controlled vs uncontrolled usage
The SwitchToggle component can be used in either a controlled or uncontrolled manner.
In controlled mode, you manage the state of the switch toggle using the checked prop and handle changes with the onChange callback. This gives you full control over the component's state.
In uncontrolled mode, the component maintains its own internal state. You can set the initial state using the defaultChecked prop, and the component will handle state changes internally.
Inline
By default the SwitchToggle is displayed as a block-level element with a label on the left and the toggle on the right. However, it can be displayed inline with other elements by setting the inline prop to true. This is useful for integrating the toggle within a larger layout without breaking the flow of the surrounding content. When displaying the SwitchToggle inline, you will likely want to adjust the alignIndicator prop to start so that the toggle appears before the label and remove the background and padding:
<SwitchToggle label="Push notifications" inline alignIndicator="start" bgFill={false} padding={0} />