Toggle
The Toggle component lets users switch between two states, like on or off. It's often used on mobile settings pages to show and change options easily.
Quick Start
- Installation
npm install @adaptavant/eds-core- Import
import { Toggle } from '@adaptavant/eds-core';
Size
Customise the size of the Toggle via the size prop.
{/* standard */}
<Toggle label="Toggle label" />
{/* large */}
<Toggle label="Toggle label" size="large" />
Description
Use the description prop when you need to provide additional secondary information.
<Toggle label="Toggle label" description="Additional information" />
Disabled
Use the isDisabled prop to show that a Toggle isn't usable.
{/* disabeld */}
<Toggle label="Toggle label" isDisabled />
Toggle Position
Use the togglePosition prop to control the placement of the label and toggle.
{/* label on right, toggle on left */}
<Toggle label="Label on right, toggle on left" togglePosition="start" description="Additional information" />
{/* label on left, toggle on right (default) */}
<Toggle label="Label on left, toggle on right" togglePosition="end" description="Additional information" />
Controlled
An uncontrolled Toggle component uses ref prop to access the current selected state. Additionally, you can maintain a React state to update other UI elements if needed.
const toggleRef = React.useRef(null);
const [selected, setSelected] = React.useState(false);
const handleChange = () => {
if (toggleRef.current) {
setSelected(toggleRef.current.checked);
}
};
return (
<Stack>
<Toggle label="Toggle me!" ref={toggleRef} onChange={handleChange} />
<Text className="text-body-12"> Status: {selected ? "On ✅" : "Off ❌"}</Text>
</Stack>
);
Uncontrolled
An uncontrolled Toggle component uses ref prop to access the current selected state. Additionally, you can maintain a React state to update other UI elements if needed.
const toggleRef = React.useRef(null);
const [selected, setSelected] = React.useState(false);
const handleChange = () => {
if (toggleRef.current) {
setSelected(toggleRef.current.checked);
}
};
return (
<Stack>
<Toggle label="Toggle me!" ref={toggleRef} onChange={handleChange} />
<Text className="text-body-12"> Status: {selected ? "On ✅" : "Off ❌"}</Text>
</Stack>
);
API Reference
Toggle
| Prop | Default | Description |
|---|---|---|
label | _ | ReactNodeLabel for the toggle describing its purpose. |
isDisabled? | false | booleanDisables the toggle, making it non-interactive and visually styled as disabled. |
size? | standard | 'standard' | 'large'The size of the toggle. |
value? | _ | stringDefines the value of the toggle input, used when submitting a form. |
checked? | _ | booleanSets the checked state of the toggle when using controlled components. |
id? | _ | stringA unique ID for the toggle. |
name? | _ | booleanThe name attribute of the toggle, useful for grouping in forms. |
description? | _ | ReactNodeDescription text displayed alongside the toggle, providing additional context. |
aria-describedby? | _ | stringThe ID of the element that describes the toggle for accessibility. |
onBlur? | _ | functionEvent handler triggered when the toggle loses focus. |
onClick? | _ | functionEvent handler triggered when the toggle is clicked. |
onChange? | _ | functionEvent handler triggered when the toggle value changes. |
togglePosition? | start | 'start' | 'end'Placement of the toggle primitive relative to the label. 'start' shows the label on the left and toggle on the right; 'end' reverses this. |
Style API
Our design system components include style props that allow you to easily customize different parts of each component to match your design needs.
Please refer to the Style API documentation for more insights.
Toggle parts
<Toggle
label="Toggle label"
description="Additional information"
className="border border-input w-full p-2"
classNames={{
togglePrimitiveControl: "bg-critical",
togglePrimitiveIcon: "fill-positive-hover",
label: "text-positive",
descriptionTrack: "gap-1",
description: "text-positive-secondary",
descriptionSpacer: "h-6 w-8",
}}
/>
| Stylable Parts | Description |
|---|---|
| root | The root container of the toggle, wrapping all inner components. |
| label | Label text associated with the toggle. |
| description | Description text itself, displayed alongside the toggle. |
| descriptionTrack | Wrapper for the description and related elements. |
| togglePrimitiveRoot | Root wrapper for the toggle primitive. |
| togglePrimitiveInput | Input element for the toggle (hidden by default). |
| togglePrimitiveControl | The visual toggle switch wraps the svg circle.(styled slider control). |
| togglePrimitiveIcon | Circle svg appears on top of toggle area. |
Usage guidelines
Do
- Binary options (active or inactive): Utilize Toggle for a binary option that can toggle between active and inactive states.
- Mobile interfaces: Opt for Toggle, particularly on mobile interfaces, where toggling takes immediate effect.
Don’t
- Choosing between related options: Avoid using Toggle when choosing between related options. Each Toggle should represent a solitary, standalone choice. For multiple related choices, consider using Checkboxes or RadioGroup instead.
Best practices
Do
When possible, provide context to the Toggle using a label.
Don’t
Truncate label text. Allow label it to wrap and form another line when necessary to ensure it remains readable.
Do
Clearly communicate the reason for disabling a Toogle and provide instructions on how to enable it, if possible.
Don’t
Employ alternative styling to convey the functionality of a switch. Consider using Toggle for a more standardized approach.