Search docs/
shadow

ion-toggle

Toggles change the state of a single option. Toggles can be switched on or off by pressing or swiping them. They can also be checked programmatically by setting the checked property.

Customization

Customizing Background

The background of the toggle track and handle can be customized using CSS variables. There are also variables for setting the background differently when the toggle is checked.

ion-toggle {
  --background: #000;
  --background-checked: #7a49a5;

  --handle-background: #7a49a5;
  --handle-background-checked: #000;
}
CopyCopied

Because these variables set the background property, which is a shorthand, it can accept any value that the background property accepts.

A more complex case may involve adding an image to the handle background.

ion-toggle {
  --handle-background-checked: #fff url(/assets/power-icon.png) no-repeat center / contain;
}
CopyCopied

Taking it a step further, we could use the ::before or ::after pseudo-elements to position text on top of the background.

ion-toggle::before {
  position: absolute;

  top: 16px;
  left: 10px;

  content: "ON";

  color: white;
  font-size: 8px;

  z-index: 1;
}
CopyCopied

Customizing Width

Adjusting the width of the toggle smaller will result in a narrower track, with the handle remaining the default width. If desired, set --handle-width to make the handle narrower.

ion-toggle {
  width: 40px;
}
CopyCopied

Adjusting the width of the toggle larger will result in a wider track, with the handle remaining the default width. If desired, set --handle-width to make the handle wider.

ion-toggle {
  width: 100px;
}
CopyCopied

Customizing Height

Adjusting the height of the toggle smaller than the default will result in the handle height auto-sizing itself to the track. In ios the handle is shorter than the track (100% - 4px) and in md the handle is taller than the track (100% + 6px).

ion-toggle {
  height: 15px;
}
CopyCopied

Note: this does not affect the handle width, width should be set using --handle-width.

Adjusting the height of the toggle larger will keep the handle in the center at the default height. This can be modified by setting --handle-height which can be set to any amount but will not exceed the --handle-max-height.

ion-toggle {
  height: 60px;
}
CopyCopied

Note: this does not affect the handle width, width should be set using --handle-width.

Customizing Spacing

The spacing refers to the horizontal gap between the handle and the track. By default, the handle has 2px of spacing around it in ios only. In md mode there is no default spacing.

To remove the horizontal spacing, set --handle-spacing to 0px.

ion-toggle {
  --handle-spacing: 0px;
}
CopyCopied

Due to the handle having a fixed height, to remove the spacing on the top and bottom, set the height to 100%.

ion-toggle {
  --handle-spacing: 0px;
  --handle-height: 100%;
}
CopyCopied

Customizing Border Radius

The --handle-border-radius can be used to change the border-radius on the handle.

ion-toggle {
  --handle-border-radius: 14px 4px 4px 14px;
}
CopyCopied

To target the border-radius only when the toggle is checked, target .toggle-checked:

ion-toggle.toggle-checked {
  --handle-border-radius: 4px 14px 14px 4px;
}
CopyCopied

Customizing Box Shadow

The --handle-box-shadow can be used to change the box-shadow on the handle.

ion-toggle {
  --handle-box-shadow: 4px 0 2px 0 red;
}
CopyCopied

To target the box shadow only when the toggle is checked, target .toggle-checked:

ion-toggle.toggle-checked {
  --handle-box-shadow: -4px 0 2px 0 red;
}
CopyCopied

See the section on customizing overflow to allow the box-shadow to overflow the toggle container.

Customizing Overflow

Setting overflow on the toggle will be inherited by the toggle handle. By default, overflow is set to hidden in ios only. The box-shadow will still appear cut off due to the contain css property. Set contain to none in order to overflow the toggle container.

ion-toggle {
  --handle-box-shadow: 0 3px 12px rgba(255, 0, 0, 0.6), 0 3px 1px rgba(50, 70, 255, 0.6);

  overflow: visible;

  contain: none;
}
CopyCopied

Usage

<!-- Default Toggle -->
<ion-toggle></ion-toggle>

<!-- Disabled Toggle -->
<ion-toggle disabled></ion-toggle>

<!-- Checked Toggle -->
<ion-toggle checked></ion-toggle>

<!-- Toggle Colors -->
<ion-toggle color="primary"></ion-toggle>
<ion-toggle color="secondary"></ion-toggle>
<ion-toggle color="danger"></ion-toggle>
<ion-toggle color="light"></ion-toggle>
<ion-toggle color="dark"></ion-toggle>

<!-- Toggles in a List -->
<ion-list>
  <ion-item>
    <ion-label>Pepperoni</ion-label>
    <ion-toggle [(ngModel)]="pepperoni"></ion-toggle>
  </ion-item>

  <ion-item>
    <ion-label>Sausage</ion-label>
    <ion-toggle [(ngModel)]="sausage" disabled="true"></ion-toggle>
  </ion-item>

  <ion-item>
    <ion-label>Mushrooms</ion-label>
    <ion-toggle [(ngModel)]="mushrooms"></ion-toggle>
  </ion-item>
</ion-list>
CopyCopied
<!-- Default Toggle -->
<ion-toggle></ion-toggle>

<!-- Disabled Toggle -->
<ion-toggle disabled></ion-toggle>

<!-- Checked Toggle -->
<ion-toggle checked></ion-toggle>

<!-- Toggle Colors -->
<ion-toggle color="primary"></ion-toggle>
<ion-toggle color="secondary"></ion-toggle>
<ion-toggle color="danger"></ion-toggle>
<ion-toggle color="light"></ion-toggle>
<ion-toggle color="dark"></ion-toggle>

<!-- Toggles in a List -->
<ion-list>
  <ion-item>
    <ion-label>Pepperoni</ion-label>
    <ion-toggle slot="end" value="pepperoni" checked></ion-toggle>
  </ion-item>

  <ion-item>
    <ion-label>Sausage</ion-label>
    <ion-toggle slot="end" value="sausage" disabled></ion-toggle>
  </ion-item>

  <ion-item>
    <ion-label>Mushrooms</ion-label>
    <ion-toggle slot="end" value="mushrooms"></ion-toggle>
  </ion-item>
</ion-list>
CopyCopied
import React, { useState } from 'react';
import { IonContent, IonHeader, IonPage, IonTitle, IonToolbar, IonToggle, IonList, IonItem, IonLabel, IonItemDivider } from '@ionic/react';

export const ToggleExamples: React.FC = () => {
  const [checked, setChecked] = useState(false);
  return (
    <IonPage>
      <IonHeader>
        <IonToolbar>
          <IonTitle>ToggleExamples</IonTitle>
        </IonToolbar>
      </IonHeader>
      <IonContent>
        <IonList>

          <IonItemDivider>Default Toggle</IonItemDivider>
          <IonItem>
            <IonLabel>Checked: {JSON.stringify(checked)}</IonLabel>
            <IonToggle checked={checked} onIonChange={e => setChecked(e.detail.checked)} />
          </IonItem>

          <IonItemDivider>Disabled Toggle</IonItemDivider>
          <IonItem><IonToggle disabled /></IonItem>

          <IonItemDivider>Checked Toggle</IonItemDivider>
          <IonItem><IonToggle checked /></IonItem>

          <IonItemDivider>Toggle Colors</IonItemDivider>
          <IonItem><IonToggle color="primary" /></IonItem>
          <IonItem><IonToggle color="secondary" /></IonItem>
          <IonItem><IonToggle color="danger" /></IonItem>
          <IonItem><IonToggle color="light" /></IonItem>
          <IonItem><IonToggle color="dark" /></IonItem>

          <IonItemDivider>Toggles in a List</IonItemDivider>
          <IonItem>
            <IonLabel>Pepperoni</IonLabel>
            <IonToggle value="pepperoni" />
          </IonItem>

          <IonItem>
            <IonLabel>Sausage</IonLabel>
            <IonToggle value="sausage" disabled={true} />
          </IonItem>

          <IonItem>
            <IonLabel>Mushrooms</IonLabel>
            <IonToggle value="mushrooms" />
          </IonItem>
        </IonList>
      </IonContent>
    </IonPage>
  );
};
CopyCopied
import { Component, State, h } from '@stencil/core';

@Component({
  tag: 'toggle-example',
  styleUrl: 'toggle-example.css'
})
export class ToggleExample {
  @State() pepperoni: boolean = false;
  @State() sausage: boolean = true;
  @State() mushrooms: boolean = false;

  render() {
    return [
      // Default Toggle
      <ion-toggle></ion-toggle>,

      // Disabled Toggle
      <ion-toggle disabled></ion-toggle>,

      // Checked Toggle
      <ion-toggle checked></ion-toggle>,

      // Toggle Colors
      <ion-toggle color="primary"></ion-toggle>,
      <ion-toggle color="secondary"></ion-toggle>,
      <ion-toggle color="danger"></ion-toggle>,
      <ion-toggle color="light"></ion-toggle>,
      <ion-toggle color="dark"></ion-toggle>,

      // Toggles in a List
      <ion-list>
        <ion-item>
          <ion-label>Pepperoni</ion-label>
          <ion-toggle checked={this.pepperoni} onIonChange={(ev) => this.pepperoni = ev.detail.checked}></ion-toggle>
        </ion-item>

        <ion-item>
          <ion-label>Sausage</ion-label>
          <ion-toggle checked={this.sausage} onIonChange={(ev) => this.sausage = ev.detail.checked} disabled={true}></ion-toggle>
        </ion-item>

        <ion-item>
          <ion-label>Mushrooms</ion-label>
          <ion-toggle checked={this.mushrooms} onIonChange={(ev) => this.mushrooms = ev.detail.checked}></ion-toggle>
        </ion-item>
      </ion-list>,

      <div>
        Pepperoni: {this.pepperoni ? "true" : "false"}<br/>
        Sausage: {this.sausage ? "true" : "false"}<br/>
        Mushrooms: {this.mushrooms ? "true" : "false"}
      </div>
    ];
  }
}
CopyCopied
<template>
  <!-- Default Toggle -->
  <ion-toggle></ion-toggle>

  <!-- Disabled Toggle -->
  <ion-toggle disabled></ion-toggle>

  <!-- Checked Toggle -->
  <ion-toggle checked></ion-toggle>

  <!-- Toggle Colors -->
  <ion-toggle color="primary"></ion-toggle>
  <ion-toggle color="secondary"></ion-toggle>
  <ion-toggle color="danger"></ion-toggle>
  <ion-toggle color="light"></ion-toggle>
  <ion-toggle color="dark"></ion-toggle>

  <!-- Toggles in a List -->
  <ion-list>
    <ion-item>
      <ion-label>Pepperoni</ion-label>
      <ion-toggle
        @ionChange="toppings.value.push($event.target.value)"
        value="pepperoni"
        :checked="toppings.value.indexOf('pepperoni') !== -1">
      </ion-toggle>
    </ion-item>

    <ion-item>
      <ion-label>Sausage</ion-label>
      <ion-toggle
        @ionChange="toppings.value.push($event.target.value)"
        value="sausage"
        :checked="toppings.value.indexOf('pepperoni') !== -1"
        disabled="true">
      </ion-toggle>
    </ion-item>

    <ion-item>
      <ion-label>Mushrooms</ion-label>
      <ion-toggle
        @ionChange="toppings.value.push($event.target.value)"
        value="mushrooms"
        :checked="toppings.value.indexOf('pepperoni') !== -1">
      </ion-toggle>
    </ion-item>
  </ion-list>
</template>

<script>
import { IonLabel, IonList, IonItem, IonToggle } from '@ionic/vue';
import { defineComponent, vue } from 'vue';

export default defineComponent({
  components: { IonLabel, IonList, IonItem, IonToggle },
  setup() {
    const toppings = ref([]);

    return { toppings };
  }
});
</script>
CopyCopied

Properties

checked

Description

If true, the toggle is selected.

Attributechecked
Typeboolean
Defaultfalse

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.

Attributecolor
Typestring | undefined

disabled

Description

If true, the user cannot interact with the toggle.

Attributedisabled
Typeboolean
Defaultfalse

mode

Description

The mode determines which platform styles to use.

Attributemode
Type"ios" | "md"

name

Description

The name of the control, which is submitted with the form data.

Attributename
Typestring
Defaultthis.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>.

Attributevalue
Typenull | string | undefined
Default'on'

Events

NameDescription
ionBlurEmitted when the toggle loses focus.
ionChangeEmitted when the value property has changed.
ionFocusEmitted when the toggle has focus.

CSS Shadow Parts

NameDescription
handleThe toggle handle, or knob, used to change the checked state.
trackThe background track of the toggle.

CSS Custom Properties

NameDescription
--backgroundBackground of the toggle
--background-checkedBackground of the toggle when checked
--border-radiusBorder radius of the toggle track
--handle-backgroundBackground of the toggle handle
--handle-background-checkedBackground of the toggle handle when checked
--handle-border-radiusBorder radius of the toggle handle
--handle-box-shadowBox shadow of the toggle handle
--handle-heightHeight of the toggle handle
--handle-max-heightMaximum height of the toggle handle
--handle-spacingHorizontal spacing around the toggle handle
--handle-transitionTransition of the toggle handle
--handle-widthWidth of the toggle handle
View Source