ion-toggle
Toggles are switches that change the state of a single option. They can be switched on or off by pressing or swiping them. Toggles can also be checked programmatically by setting the checked
property.
Basic Usage
On / Off Labels
Toggles can enable on/off labels by setting the enableOnOffLabels
property. This is important for accessibility as it makes it easier to differentiate between a checked and unchecked toggle.
Toggles in a List
Toggles can also be used in a list view by using the Item and List components.
Label Placement
Developers can use the labelPlacement
property to control how the label is placed relative to the control.
Alignment
Developers can use the alignment
property to control how the label and control are aligned on the cross axis. This property mirrors the flexbox align-items
property.
Stacked toggles can be aligned using the alignment
property. This can be useful when the label and control need to be centered horizontally.
Justification
Developers can use the justify
property to control how the label and control are packed on a line.
Theming
Colors
CSS Custom Properties
CSS custom properties can be combined with standard CSS to target different parts of a toggle. We can modify the width
and height
of the toggle directly to change the size of the track, while using the --handle-width
and --handle-height
custom properties to customize the handle size.
CSS Shadow Parts
We can further customize toggle by targeting specific shadow parts that are exposed. Any CSS property on these parts can be styled and they can also be combined with CSS custom properties.
Migrating from Legacy Toggle Syntax
A simpler toggle syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an toggle, resolves accessibility issues, and improves the developer experience.
While developers can continue using the legacy syntax, we recommend migrating as soon as possible.
Using the Modern Syntax
Using the modern syntax involves removing the ion-label
and passing the label directly inside of ion-toggle
. The placement of the label can be configured using the labelPlacement
property on ion-toggle
. The way the label and the control are packed on a line can be controlled using the justify
property on ion-toggle
.
- JavaScript
- Angular
- React
- Vue
<!-- Basic -->
<!-- Before -->
<ion-item>
<ion-label>Notifications</ion-label>
<ion-toggle></ion-toggle>
</ion-item>
<!-- After -->
<ion-item>
<ion-toggle>Notifications</ion-toggle>
</ion-item>
<!-- Fixed Labels -->
<!-- Before -->
<ion-item>
<ion-label position="fixed">Notifications</ion-label>
<ion-toggle></ion-toggle>
</ion-item>
<!-- After -->
<ion-item>
<ion-toggle label-placement="fixed">Notifications</ion-toggle>
</ion-item>
<!-- Toggle at the start of line, Label at the end of line -->
<!-- Before -->
<ion-item>
<ion-label slot="end">Notifications</ion-label>
<ion-toggle></ion-toggle>
</ion-item>
<!-- After -->
<ion-item>
<ion-toggle label-placement="end">Notifications</ion-toggle>
</ion-item>