ionic-team · thetaPC · Mar 11, 2025 · Mar 10, 2025 · Mar 10, 2025 · Mar 10, 2025
diff --git a/docs/api/toggle.md b/docs/api/toggle.md
@@ -73,6 +73,16 @@ import Justify from '@site/static/usage/v8/toggle/justify/index.md';
 
 <Justify />
 
+## 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.
+
+import HelperError from '@site/static/usage/v8/toggle/helper-error/index.md';
+
+<HelperError />
+
 ## Theming
 
 ### Colors

diff --git a/static/usage/v8/toggle/helper-error/angular/example_component_html.md b/static/usage/v8/toggle/helper-error/angular/example_component_html.md
@@ -0,0 +1,13 @@
+```html
+<form [formGroup]="myForm">
+  <ion-toggle
+    formControlName="wifi"
+    helperText="Enable to connect to available networks"
+    errorText="Must be enabled to access the internet"
+    justify="space-between"
+    (ionChange)="onChange()"
+  >
+    Wi-Fi
+  </ion-toggle>
+</form>
+```
diff --git a/static/usage/v8/toggle/helper-error/angular/example_component_ts.md b/static/usage/v8/toggle/helper-error/angular/example_component_ts.md
@@ -0,0 +1,28 @@
+```ts
+import { Component } from '@angular/core';
+import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
+import { IonToggle } from '@ionic/angular/standalone';
+
+@Component({
+  selector: 'app-example',
+  standalone: true,
+  imports: [IonToggle, ReactiveFormsModule],
+  templateUrl: './example.component.html',
+  styleUrl: './example.component.css',
+})
+export class ExampleComponent {
+  myForm: FormGroup;
+
+  constructor(private fb: FormBuilder) {
+    this.myForm = this.fb.group({
+      wifi: [true, Validators.requiredTrue],
+    });
+  }
+
+  onChange() {
+    // Mark the control as touched to trigger the error message
+    // without requiring the toggle to be blurred first
+    this.myForm.get('wifi')!.markAsTouched();
+  }
+}
+```
diff --git a/static/usage/v8/toggle/helper-error/demo.html b/static/usage/v8/toggle/helper-error/demo.html
@@ -0,0 +1,48 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Input</title>
+    <link rel="stylesheet" href="../../common.css" />
+    <script src="../../common.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@8/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@8/css/ionic.bundle.css" />
+  </head>
+
+  <body>
+    <style>
+      ion-toggle {
+        width: 300px;
+      }
+    </style>
+
+    <div class="container">
+      <ion-toggle
+        helper-text="Enable to connect to available networks"
+        error-text="Must be enabled to access the internet"
+        checked
+      >
+        Wi-Fi
+      </ion-toggle>
+    </div>
+
+    <script>
+      const wifi = document.querySelector('ion-toggle');
+
+      wifi.addEventListener('ionChange', (event) => validateToggle(event));
+
+      const validateToggle = (event) => {
+        wifi.classList.add('ion-touched');
+
+        if (!event.detail.checked) {
+          wifi.classList.add('ion-invalid');
+          wifi.classList.remove('ion-valid');
+        } else {
+          wifi.classList.remove('ion-invalid');
+          wifi.classList.add('ion-valid');
+        }
+      };
+    </script>
+  </body>
+</html>
diff --git a/static/usage/v8/toggle/helper-error/index.md b/static/usage/v8/toggle/helper-error/index.md
@@ -0,0 +1,24 @@
+import Playground from '@site/src/components/global/Playground';
+
+import javascript from './javascript.md';
+import react from './react.md';
+import vue from './vue.md';
+
+import angular_example_component_html from './angular/example_component_html.md';
+import angular_example_component_ts from './angular/example_component_ts.md';
+
+<Playground
+  version="8"
+  code={{
+    javascript,
+    react,
+    vue,
+    angular: {
+      files: {
+        'src/app/example.component.html': angular_example_component_html,
+        'src/app/example.component.ts': angular_example_component_ts,
+      },
+    },
+  }}
+  src="usage/v8/toggle/helper-error/demo.html"
+/>
diff --git a/static/usage/v8/toggle/helper-error/javascript.md b/static/usage/v8/toggle/helper-error/javascript.md
@@ -0,0 +1,28 @@
+```html
+<ion-toggle
+  helper-text="Enable to connect to available networks"
+  error-text="Must be enabled to access the internet"
+  justify="space-between"
+  checked
+>
+  Wi-Fi
+</ion-toggle>
+
+<script>
+  const wifi = document.querySelector('ion-toggle');
+
+  wifi.addEventListener('ionChange', (event) => validateToggle(event));
+
+  const validateToggle = (event) => {
+    wifi.classList.add('ion-touched');
+
+    if (!event.detail.checked) {
+      wifi.classList.add('ion-invalid');
+      wifi.classList.remove('ion-valid');
+    } else {
+      wifi.classList.remove('ion-invalid');
+      wifi.classList.add('ion-valid');
+    }
+  };
+</script>
+```
diff --git a/static/usage/v8/toggle/helper-error/react.md b/static/usage/v8/toggle/helper-error/react.md
@@ -0,0 +1,38 @@
+```tsx
+import React, { useRef, useState } from 'react';
+import { IonToggle, ToggleCustomEvent } from '@ionic/react';
+
+function Example() {
+  const wifiRef = useRef<HTMLIonToggleElement>(null);
+
+  const [isTouched, setIsTouched] = useState<boolean>(false);
+  const [isValid, setIsValid] = useState<boolean | undefined>();
+  const [isChecked, setIsChecked] = useState<boolean>(true);
+
+  const validateToggle = (event: ToggleCustomEvent<{ checked: boolean }>) => {
+    setIsTouched(true);
+    setIsChecked(event.detail.checked);
+    setIsValid(event.detail.checked);
+  };
+
+  return (
+    <>
+      <IonToggle
+        ref={wifiRef}
+        className={`${isValid ? 'ion-valid' : ''} ${isValid === false ? 'ion-invalid' : ''} ${
+          isTouched ? 'ion-touched' : ''
+        }`}
+        helperText="Enable to connect to available networks"
+        errorText="Must be enabled to access the internet"
+        justify="space-between"
+        checked={isChecked}
+        onIonChange={(event) => validateToggle(event)}
+      >
+        Wi-Fi
+      </IonToggle>
+    </>
+  );
+}
+
+export default Example;
+```
diff --git a/static/usage/v8/toggle/helper-error/vue.md b/static/usage/v8/toggle/helper-error/vue.md
@@ -0,0 +1,47 @@
+```html
+<template>
+  <ion-toggle
+    v-model="wifi"
+    helper-text="Enable to connect to available networks"
+    error-text="Must be enabled to access the internet"
+    justify="space-between"
+    @ionChange="validateToggle"
+    :class="{
+      'ion-valid': isValid,
+      'ion-invalid': isValid === false,
+      'ion-touched': isTouched,
+    }"
+  >
+    Wi-Fi
+  </ion-toggle>
+</template>
+
+<script lang="ts">
+  import { defineComponent, ref } from 'vue';
+  import { IonToggle, IonButton, ToggleCustomEvent } from '@ionic/vue';
+
+  export default defineComponent({
+    components: {
+      IonToggle,
+      IonButton,
+    },
+    setup() {
+      const wifi = ref(true);
+      const isTouched = ref(false);
+      const isValid = ref<boolean | undefined>();
+
+      const validateToggle = (event: ToggleCustomEvent<{ checked: boolean }>) => {
+        isTouched.value = true;
+        isValid.value = event.detail.checked;
+      };
+
+      return {
+        wifi,
+        isTouched,
+        isValid,
+        validateToggle,
+      };
+    },
+  });
+</script>
+```