diff --git a/docs/api/input.md b/docs/api/input.md index 6bdecfc9568..dd7507df3c4 100644 --- a/docs/api/input.md +++ b/docs/api/input.md @@ -70,8 +70,6 @@ import NoVisibleLabel from '@site/static/usage/v7/input/no-visible-label/index.m - - ## Clear Options Inputs offer two options for clearing the input based on how you interact with it. The first way is by adding the `clearInput` property which will show a clear button when the input has a `value`. The second way is the `clearOnEdit` property which will clear the input after it has been blurred and then typed in again. Inputs with a `type` set to `"password"` will have `clearOnEdit` enabled by default. diff --git a/docs/api/textarea.md b/docs/api/textarea.md index 9315c981358..8bc1d7ee99d 100644 --- a/docs/api/textarea.md +++ b/docs/api/textarea.md @@ -29,14 +29,40 @@ import BasicPlayground from '@site/static/usage/v7/textarea/basic/index.md'; -## Label Placement +## Labels + +Labels should be used to describe the textarea. They can be used visually, and they will also be read out by screen readers when the user is focused on the textarea. This makes it easy for the user to understand the intent of the textarea. Textarea has several ways to assign a label: + +- `label` property: used for plaintext labels +- `label` slot: used for custom HTML labels (experimental) +- `aria-label`: used to provide a label for screen readers but adds no visible label + +### Label Placement Labels will take up the width of their content by default. Developers can use the `labelPlacement` property to control how the label is placed relative to the control. -import Labels from '@site/static/usage/v7/textarea/label-placement/index.md'; +import LabelPlacement from '@site/static/usage/v7/textarea/label-placement/index.md'; +### Label Slot (experimental) + +While plaintext labels should be passed in via the `label` property, if custom HTML is needed, it can be passed through the `label` slot instead. + +Note that this feature is considered experimental because it relies on a simulated version of [Web Component slots](https://developer.mozilla.org/en-US/docs/Web/API/Web_components/Using_templates_and_slots). As a result, the simulated behavior may not exactly match the native slot behavior. + +import LabelSlot from '@site/static/usage/v7/textarea/label-slot/index.md'; + + + +### No Visible Label + +If no visible label is needed, developers should still supply an `aria-label` so the textarea is accessible to screen readers. + +import NoVisibleLabel from '@site/static/usage/v7/textarea/no-visible-label/index.md'; + + + ## Filled Textareas Material Design offers filled styles for a textarea. The `fill` property on the item can be set to either `"solid"` or `"outline"`. diff --git a/static/usage/v7/textarea/label-slot/angular.md b/static/usage/v7/textarea/label-slot/angular.md new file mode 100644 index 00000000000..9c8e09ec88a --- /dev/null +++ b/static/usage/v7/textarea/label-slot/angular.md @@ -0,0 +1,9 @@ +```html + + + +
Comments (Required)
+ + + +``` diff --git a/static/usage/v7/textarea/label-slot/demo.html b/static/usage/v7/textarea/label-slot/demo.html new file mode 100644 index 00000000000..f71b8af342a --- /dev/null +++ b/static/usage/v7/textarea/label-slot/demo.html @@ -0,0 +1,28 @@ + + + + + + textarea + + + + + + + + + +
+ + + +
Comments (Required)
+ + + +
+ + + + diff --git a/static/usage/v7/textarea/label-slot/index.md b/static/usage/v7/textarea/label-slot/index.md new file mode 100644 index 00000000000..8af442e5bce --- /dev/null +++ b/static/usage/v7/textarea/label-slot/index.md @@ -0,0 +1,12 @@ +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'; + + diff --git a/static/usage/v7/textarea/label-slot/javascript.md b/static/usage/v7/textarea/label-slot/javascript.md new file mode 100644 index 00000000000..199978f9352 --- /dev/null +++ b/static/usage/v7/textarea/label-slot/javascript.md @@ -0,0 +1,9 @@ +```html + + + +
Comments (Required)
+ + + +``` diff --git a/static/usage/v7/textarea/label-slot/react.md b/static/usage/v7/textarea/label-slot/react.md new file mode 100644 index 00000000000..648c0aafb04 --- /dev/null +++ b/static/usage/v7/textarea/label-slot/react.md @@ -0,0 +1,17 @@ +```tsx +import React from 'react'; +import { IonTextarea, IonItem, IonList, IonText } from '@ionic/react'; + +function Example() { + return ( + + + +
Comments (Required)
+ + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/textarea/label-slot/vue.md b/static/usage/v7/textarea/label-slot/vue.md new file mode 100644 index 00000000000..0c5d90db33c --- /dev/null +++ b/static/usage/v7/textarea/label-slot/vue.md @@ -0,0 +1,20 @@ +```html + + + +``` diff --git a/static/usage/v7/textarea/no-visible-label/angular.md b/static/usage/v7/textarea/no-visible-label/angular.md new file mode 100644 index 00000000000..2f4baaa7511 --- /dev/null +++ b/static/usage/v7/textarea/no-visible-label/angular.md @@ -0,0 +1,7 @@ +```html + + + + + +``` diff --git a/static/usage/v7/textarea/no-visible-label/demo.html b/static/usage/v7/textarea/no-visible-label/demo.html new file mode 100644 index 00000000000..3d4e4f4a764 --- /dev/null +++ b/static/usage/v7/textarea/no-visible-label/demo.html @@ -0,0 +1,26 @@ + + + + + + textarea + + + + + + + + + +
+ + + + + +
+ + + + diff --git a/static/usage/v7/textarea/no-visible-label/index.md b/static/usage/v7/textarea/no-visible-label/index.md new file mode 100644 index 00000000000..ca0024ae17c --- /dev/null +++ b/static/usage/v7/textarea/no-visible-label/index.md @@ -0,0 +1,12 @@ +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'; + + diff --git a/static/usage/v7/textarea/no-visible-label/javascript.md b/static/usage/v7/textarea/no-visible-label/javascript.md new file mode 100644 index 00000000000..2f4baaa7511 --- /dev/null +++ b/static/usage/v7/textarea/no-visible-label/javascript.md @@ -0,0 +1,7 @@ +```html + + + + + +``` diff --git a/static/usage/v7/textarea/no-visible-label/react.md b/static/usage/v7/textarea/no-visible-label/react.md new file mode 100644 index 00000000000..c024d0fee66 --- /dev/null +++ b/static/usage/v7/textarea/no-visible-label/react.md @@ -0,0 +1,15 @@ +```tsx +import React from 'react'; +import { IonTextarea, IonItem, IonList } from '@ionic/react'; + +function Example() { + return ( + + + + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/textarea/no-visible-label/vue.md b/static/usage/v7/textarea/no-visible-label/vue.md new file mode 100644 index 00000000000..fc77027d770 --- /dev/null +++ b/static/usage/v7/textarea/no-visible-label/vue.md @@ -0,0 +1,18 @@ +```html + + + +```