| title | ion-toggle |
|---|
import Props from '@ionic-internal/component-api/v8/toggle/props.md'; import Events from '@ionic-internal/component-api/v8/toggle/events.md'; import Methods from '@ionic-internal/component-api/v8/toggle/methods.md'; import Parts from '@ionic-internal/component-api/v8/toggle/parts.md'; import CustomProps from '@ionic-internal/component-api/v8/toggle/custom-props.mdx'; import Slots from '@ionic-internal/component-api/v8/toggle/slots.md';
<title>ion-toggle: Custom Toggle Button for Ionic Applications</title>import EncapsulationPill from '@components/page/api/EncapsulationPill';
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.
import Basic from '@site/static/usage/v8/toggle/basic/index.md';
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.
import OnOff from '@site/static/usage/v8/toggle/on-off/index.md';
Toggles can also be used in a list view by using the Item and List components.
import List from '@site/static/usage/v8/toggle/list/index.md';
Developers can use the labelPlacement property to control how the label is placed relative to the control.
import LabelPlacement from '@site/static/usage/v8/toggle/label-placement/index.md';
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.
:::
import Alignment from '@site/static/usage/v8/toggle/alignment/index.md';
Developers can use the justify property to control how the label and control are packed on a line.
import Justify from '@site/static/usage/v8/toggle/justify/index.md';
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.
import HelperError from '@site/static/usage/v8/toggle/helper-error/index.md';
import Colors from '@site/static/usage/v8/toggle/theming/colors/index.md';
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.
import CSSProps from '@site/static/usage/v8/toggle/theming/css-properties/index.md';
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.
import CSSParts from '@site/static/usage/v8/toggle/theming/css-shadow-parts/index.md';
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 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.
import Migration from '@site/static/usage/v8/toggle/migration/index.md';
:::note
In past versions of Ionic, ion-item was required for ion-toggle to function properly. Starting in Ionic 7.0, ion-toggle should only be used in an ion-item when the item is placed in an ion-list. Additionally, ion-item is no longer required for ion-toggle to function properly.
:::
Ionic uses heuristics to detect if an app is using the modern toggle syntax. In some instances, it may be preferable to continue using the legacy syntax. Developers can set the legacy property on ion-toggle to true to force that instance of the toggle to use the legacy syntax.
interface ToggleChangeEventDetail<T = any> {
value: T;
checked: boolean;
}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;
}