diff --git a/docs/api/checkbox.md b/docs/api/checkbox.md index 900f827e237..a7b733f201d 100644 --- a/docs/api/checkbox.md +++ b/docs/api/checkbox.md @@ -74,6 +74,16 @@ import LabelLink from '@site/static/usage/v8/checkbox/label-link/index.md'; +## Helper & Error Text + +Helper and error text can be used inside of a checkbox 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-checkbox`. 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/checkbox/helper-error/index.md'; + + + ## Theming ### CSS Custom Properties diff --git a/static/usage/v8/checkbox/helper-error/angular/example_component_html.md b/static/usage/v8/checkbox/helper-error/angular/example_component_html.md new file mode 100644 index 00000000000..7153841ac36 --- /dev/null +++ b/static/usage/v8/checkbox/helper-error/angular/example_component_html.md @@ -0,0 +1,15 @@ +```html +
+ + I agree to the terms and conditions + + +
+ + Submit +
+``` diff --git a/static/usage/v8/checkbox/helper-error/angular/example_component_ts.md b/static/usage/v8/checkbox/helper-error/angular/example_component_ts.md new file mode 100644 index 00000000000..d8611d00de6 --- /dev/null +++ b/static/usage/v8/checkbox/helper-error/angular/example_component_ts.md @@ -0,0 +1,29 @@ +```ts +import { Component } from '@angular/core'; +import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms'; +import { IonCheckbox, IonButton } from '@ionic/angular/standalone'; + +@Component({ + selector: 'app-example', + standalone: true, + imports: [IonCheckbox, IonButton, ReactiveFormsModule], + templateUrl: './example.component.html', + styleUrl: './example.component.css', +}) +export class ExampleComponent { + myForm: FormGroup; + + constructor(private fb: FormBuilder) { + this.myForm = this.fb.group({ + agree: [false, Validators.requiredTrue], + }); + } + + onSubmit() { + // Mark the control as touched to trigger the error message. + // This is needed if the user submits the form without interacting + // with the checkbox. + this.myForm.get('agree')!.markAsTouched(); + } +} +``` diff --git a/static/usage/v8/checkbox/helper-error/demo.html b/static/usage/v8/checkbox/helper-error/demo.html new file mode 100644 index 00000000000..f16fd9b8503 --- /dev/null +++ b/static/usage/v8/checkbox/helper-error/demo.html @@ -0,0 +1,55 @@ + + + + + + Input + + + + + + + +
+
+ + I agree to the terms and conditions + + +
+ + Submit +
+
+ + + + diff --git a/static/usage/v8/checkbox/helper-error/index.md b/static/usage/v8/checkbox/helper-error/index.md new file mode 100644 index 00000000000..8a49f53d9c8 --- /dev/null +++ b/static/usage/v8/checkbox/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'; + + diff --git a/static/usage/v8/checkbox/helper-error/javascript.md b/static/usage/v8/checkbox/helper-error/javascript.md new file mode 100644 index 00000000000..0f7d8901ae2 --- /dev/null +++ b/static/usage/v8/checkbox/helper-error/javascript.md @@ -0,0 +1,37 @@ +```html +
+ + I agree to the terms and conditions + + +
+ + Submit +
+ + +``` diff --git a/static/usage/v8/checkbox/helper-error/react.md b/static/usage/v8/checkbox/helper-error/react.md new file mode 100644 index 00000000000..7c861fce639 --- /dev/null +++ b/static/usage/v8/checkbox/helper-error/react.md @@ -0,0 +1,52 @@ +```tsx +import React, { useRef, useState } from 'react'; +import { IonCheckbox, IonButton, CheckboxCustomEvent } from '@ionic/react'; + +function Example() { + const [isTouched, setIsTouched] = useState(false); + const [isValid, setIsValid] = useState(); + + const agreeRef = useRef(null); + + const validateCheckbox = (event: CheckboxCustomEvent<{ checked: boolean }>) => { + setIsTouched(true); + setIsValid(event.detail.checked); + }; + + const submit = (event: React.FormEvent) => { + event.preventDefault(); + + if (agreeRef.current) { + validateCheckbox({ detail: { checked: agreeRef.current.checked } } as CheckboxCustomEvent<{ + checked: boolean; + }>); + } + }; + + return ( + <> +
+ validateCheckbox(event)} + > + I agree to the terms and conditions + + +
+ + + Submit + +
+ + ); +} + +export default Example; +``` diff --git a/static/usage/v8/checkbox/helper-error/vue.md b/static/usage/v8/checkbox/helper-error/vue.md new file mode 100644 index 00000000000..46b554c9553 --- /dev/null +++ b/static/usage/v8/checkbox/helper-error/vue.md @@ -0,0 +1,53 @@ +```html + + + +```