ion-toggle

shadow

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.

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

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 & Record<never, never> ｜ 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')

mode

Description	The mode determines which platform styles to use.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

name

Description	The name of the control, which is submitted with the form data.
Attribute	name
Type	string
Default	this.inputId

value

Description	The value of the toggle does not mean if it's checked or not, use the checked property for that. The value of a toggle is analogous to the value of a <input type="checkbox">, it's only used when the toggle participates in a native <form>.
Attribute	value
Type	null ｜ string ｜ undefined
Default	'on'

Events

Name	Description	Bubbles
ionBlur	Emitted when the toggle loses focus.	Yes
ionChange	Emitted when the value property has changed.	Yes
ionFocus	Emitted when the toggle has focus.	Yes

Methods

No public methods available for this component.

CSS Shadow Parts

Name	Description
handle	The toggle handle, or knob, used to change the checked state.
track	The background track of the toggle.

CSS Custom Properties

Name	Description
--background	Background of the toggle
--background-checked	Background of the toggle when checked
--border-radius	Border radius of the toggle track
--handle-background	Background of the toggle handle
--handle-background-checked	Background of the toggle handle when checked
--handle-border-radius	Border radius of the toggle handle
--handle-box-shadow	Box shadow of the toggle handle
--handle-height	Height of the toggle handle
--handle-max-height	Maximum height of the toggle handle
--handle-spacing	Horizontal spacing around the toggle handle
--handle-transition	Transition of the toggle handle
--handle-width	Width of the toggle handle

Slots

No slots available for this component.