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.
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 |
---|---|
ionBlur | Emitted when the toggle loses focus. |
ionChange | Emitted when the value property has changed. |
ionFocus | Emitted when the toggle has focus. |
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.