docs(checkbox): show how to prevent toggling checkbox with link (#3584)

ionic-team · Apr 9, 2024 · 9d7b62b · 9d7b62b
1 parent eddeb20
commit 9d7b62b
Show file tree

Hide file tree

Showing 14 changed files with 196 additions and 0 deletions.
diff --git a/docs/api/checkbox.md b/docs/api/checkbox.md
@@ -65,6 +65,14 @@ import Justify from '@site/static/usage/v8/checkbox/justify/index.md';
 import Indeterminate from '@site/static/usage/v8/checkbox/indeterminate/index.md';
 
 <Indeterminate />
+
+## Links inside of Labels
+
+Checkbox labels can sometimes be accompanied with links. These links can provide more information related to the checkbox. However, clicking the link should not check the checkbox. To achieve this, we can use [stopPropagation](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) to prevent the click event from bubbling. When using this approach, the rest of the label still remains clickable.
+
+import LabelLink from '@site/static/usage/v8/checkbox/label-link/index.md';
+
+<LabelLink />
 
 ## Theming
 

diff --git a/static/usage/v7/checkbox/label-link/angular.md b/static/usage/v7/checkbox/label-link/angular.md
@@ -0,0 +1,3 @@
+```html
+<ion-checkbox>I agree to the <a href="#" (click)="$event.stopPropagation()">terms and conditions</a></ion-checkbox>
+```
diff --git a/static/usage/v7/checkbox/label-link/demo.html b/static/usage/v7/checkbox/label-link/demo.html
@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Checkbox</title>
+    <link rel="stylesheet" href="../../common.css" />
+    <script src="../../common.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@7/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7/css/ionic.bundle.css" />
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <ion-checkbox
+            >I agree to the <a href="#" onclick="event.stopPropagation()">terms and conditions</a></ion-checkbox
+          >
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v7/checkbox/label-link/index.md b/static/usage/v7/checkbox/label-link/index.md
@@ -0,0 +1,17 @@
+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 from './angular.md';
+
+<Playground
+  version="7"
+  code={{
+    javascript,
+    react,
+    vue,
+    angular,
+  }}
+  src="usage/v7/checkbox/label-link/demo.html"
+/>
diff --git a/static/usage/v7/checkbox/label-link/javascript.md b/static/usage/v7/checkbox/label-link/javascript.md
@@ -0,0 +1,3 @@
+```html
+<ion-checkbox>I agree to the <a href="#" onclick="event.stopPropagation()">terms and conditions</a></ion-checkbox>
+```
diff --git a/static/usage/v7/checkbox/label-link/react.md b/static/usage/v7/checkbox/label-link/react.md
@@ -0,0 +1,29 @@
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { IonCheckbox } from '@ionic/react';
+
+function Example() {
+  const ref = useRef<HTMLAnchorElement>(null);
+
+  /**
+   * IonCheckbox will be listening for the native click event here so we need
+   * to call stopPropagation when the native click event instead of when the
+   * synthetic click event fires.
+   */
+  useEffect(() => {
+    ref.current?.addEventListener('click', (event) => {
+      event.stopPropagation();
+    });
+  }, [ref]);
+
+  return (
+    <IonCheckbox>
+      I agree to the{' '}
+      <a href="#" ref={ref}>
+        terms and conditions
+      </a>
+    </IonCheckbox>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v7/checkbox/label-link/vue.md b/static/usage/v7/checkbox/label-link/vue.md
@@ -0,0 +1,14 @@
+```html
+<template>
+  <ion-checkbox>I agree to the <a href="#" @click="$event.stopPropagation()">terms and conditions</a></ion-checkbox>
+</template>
+
+<script lang="ts">
+  import { IonCheckbox } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonCheckbox },
+  });
+</script>
+```
diff --git a/static/usage/v8/checkbox/label-link/angular.md b/static/usage/v8/checkbox/label-link/angular.md
@@ -0,0 +1,3 @@
+```html
+<ion-checkbox>I agree to the <a href="#" (click)="$event.stopPropagation()">terms and conditions</a></ion-checkbox>
+```
diff --git a/static/usage/v8/checkbox/label-link/demo.html b/static/usage/v8/checkbox/label-link/demo.html
@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Checkbox</title>
+    <link rel="stylesheet" href="../../common.css" />
+    <script src="../../common.js"></script>
+    <script type="module" src="https://cdn.jsdelivr.net/npm/@ionic/core@next/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@next/css/ionic.bundle.css" />
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <ion-checkbox
+            >I agree to the <a href="#" onclick="event.stopPropagation()">terms and conditions</a></ion-checkbox
+          >
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v8/checkbox/label-link/index.md b/static/usage/v8/checkbox/label-link/index.md
@@ -0,0 +1,17 @@
+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 from './angular.md';
+
+<Playground
+  version="8"
+  code={{
+    javascript,
+    react,
+    vue,
+    angular,
+  }}
+  src="usage/v8/checkbox/label-link/demo.html"
+/>
diff --git a/static/usage/v8/checkbox/label-link/javascript.md b/static/usage/v8/checkbox/label-link/javascript.md
@@ -0,0 +1,3 @@
+```html
+<ion-checkbox>I agree to the <a href="#" onclick="event.stopPropagation()">terms and conditions</a></ion-checkbox>
+```
diff --git a/static/usage/v8/checkbox/label-link/react.md b/static/usage/v8/checkbox/label-link/react.md
@@ -0,0 +1,29 @@
+```tsx
+import React, { useEffect, useRef } from 'react';
+import { IonCheckbox } from '@ionic/react';
+
+function Example() {
+  const ref = useRef<HTMLAnchorElement>(null);
+
+  /**
+   * IonCheckbox will be listening for the native click event here so we need
+   * to call stopPropagation when the native click event instead of when the
+   * synthetic click event fires.
+   */
+  useEffect(() => {
+    ref.current?.addEventListener('click', (event) => {
+      event.stopPropagation();
+    });
+  }, [ref]);
+
+  return (
+    <IonCheckbox>
+      I agree to the{' '}
+      <a href="#" ref={ref}>
+        terms and conditions
+      </a>
+    </IonCheckbox>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v8/checkbox/label-link/vue.md b/static/usage/v8/checkbox/label-link/vue.md
@@ -0,0 +1,14 @@
+```html
+<template>
+  <ion-checkbox>I agree to the <a href="#" @click="$event.stopPropagation()">terms and conditions</a></ion-checkbox>
+</template>
+
+<script lang="ts">
+  import { IonCheckbox } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonCheckbox },
+  });
+</script>
+```
diff --git a/versioned_docs/version-v7/api/checkbox.md b/versioned_docs/version-v7/api/checkbox.md
@@ -67,6 +67,14 @@ import Indeterminate from '@site/static/usage/v7/checkbox/indeterminate/index.md
 
 <Indeterminate />
 
+## Links inside of Labels
+
+Checkbox labels can sometimes be accompanied with links. These links can provide more information related to the checkbox. However, clicking the link should not check the checkbox. To achieve this, we can use [stopPropagation](https://developer.mozilla.org/en-US/docs/Web/API/Event/stopPropagation) to prevent the click event from bubbling. When using this approach, the rest of the label still remains clickable.
+
+import LabelLink from '@site/static/usage/v7/checkbox/label-link/index.md';
+
+<LabelLink />
+
 ## Theming
 
 ### CSS Custom Properties