ion-toggle

shadow

See More

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.

note

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.

Helper & Error Text

Helper and error text can be used inside of a toggle with the helperText and errorText property. The error text will not be displayed unless the ion-invalid and ion-touched classes are added to the ion-toggle. This ensures errors are not shown before the user has a chance to enter data.

In Angular, this is done automatically through form validation. In JavaScript, React and Vue, the class needs to be manually added based on your own validation.

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.

Interfaces

ToggleChangeEventDetail

interface ToggleChangeEventDetail<T = any> {
  value: T;
  checked: boolean;
}

ToggleCustomEvent

While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.

interface ToggleCustomEvent<T = any> extends CustomEvent {
  detail: ToggleChangeEventDetail<T>;
  target: HTMLIonToggleElement;
}

Properties

alignment

Description	How to control the alignment of the toggle and label on the cross axis. "start": The label and control will appear on the left of the cross axis in LTR, and on the right side in RTL. "center": The label and control will appear at the center of the cross axis in both LTR and RTL. Setting this property will change the toggle display to block.
Attribute	alignment
Type	"center" ｜ "start" ｜ undefined
Default	undefined

checked

Description	If true, the toggle is selected.
Attribute	checked
Type	boolean
Default	false

color

Description	The color to use from your application's color palette. Default options are: "primary", "secondary", "tertiary", "success", "warning", "danger", "light", "medium", and "dark". For more information on colors, see theming.
Attribute	color
Type	"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string ｜ undefined
Default	undefined

disabled

Description	If true, the user cannot interact with the toggle.
Attribute	disabled
Type	boolean
Default	false

enableOnOffLabels

Description	Enables the on/off accessibility switch labels within the toggle.
Attribute	enable-on-off-labels
Type	boolean ｜ undefined
Default	config.get('toggleOnOffLabels')

errorText

Description	Text that is placed under the toggle label and displayed when an error is detected.
Attribute	error-text
Type	string ｜ undefined
Default	undefined

helperText

Description	Text that is placed under the toggle label and displayed when no error is detected.
Attribute	helper-text
Type	string ｜ undefined
Default	undefined

justify

Description	How to pack the label and toggle within a line. "start": The label and toggle will appear on the left in LTR and on the right in RTL. "end": The label and toggle will appear on the right in LTR and on the left in RTL. "space-between": The label and toggle will appear on opposite ends of the line with space between the two elements. Setting this property will change the toggle display to block.
Attribute	justify
Type	"end" ｜ "space-between" ｜ "start" ｜ undefined
Default	undefined

labelPlacement