diff --git a/docs/api/input.md b/docs/api/input.md index 02c34e0d726..6bdecfc9568 100644 --- a/docs/api/input.md +++ b/docs/api/input.md @@ -36,8 +36,15 @@ import Types from '@site/static/usage/v7/input/types/index.md'; +## Labels -## Label Placement +Labels should be used to describe the input. They can be used visually, and they will also be read out by screen readers when the user is focused on the input. This makes it easy for the user to understand the intent of the input. Input 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. @@ -45,6 +52,25 @@ import LabelPlacement from '@site/static/usage/v7/input/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/input/label-slot/index.md'; + + + +### No Visible Label + +If no visible label is needed, developers should still supply an `aria-label` so the input is accessible to screen readers. + +import NoVisibleLabel from '@site/static/usage/v7/input/no-visible-label/index.md'; + + + + ## Clear Options diff --git a/docs/api/range.md b/docs/api/range.md index be52a7b1fea..3ff4f6adb35 100644 --- a/docs/api/range.md +++ b/docs/api/range.md @@ -24,10 +24,11 @@ By default the Range slider has a minimum value of `0` and a maximum value of `1 ## Labels -Range has several options for supplying a label for the component: +Labels should be used to describe the range. They can be used visually, and they will also be read out by screen readers when the user is focused on the range. This makes it easy for the user to understand the intent of the range. Range has several ways to assign a label: + - `label` property: used for plaintext labels - `label` slot: used for custom HTML labels -- `aria-label`: used for ranges with no visible label +- `aria-label`: used to provide a label for screen readers but adds no visible label ### Label Placement @@ -47,7 +48,7 @@ import LabelSlotPlayground from '@site/static/usage/v7/range/label-slot/index.md ### No Visible Label -If no visible label is needed, devs should still supply an `aria-label` so the range is accessible to screen readers. +If no visible label is needed, developers should still supply an `aria-label` so the range is accessible to screen readers. import NoVisibleLabel from '@site/static/usage/v7/range/no-visible-label/index.md'; diff --git a/docs/api/select.md b/docs/api/select.md index 2636e7d04bb..d34b353cf1b 100644 --- a/docs/api/select.md +++ b/docs/api/select.md @@ -26,11 +26,13 @@ If `value` is set on the ``, the selected option will be chosen base ## Labels +Labels should be used to describe the select. They can be used visually, and they will also be read out by screen readers when the user is focused on the select. This makes it easy for the user to understand the intent of the select. Select has several ways to assign a label: + Select has several options for supplying a label for the component: - `label` property: used for plaintext labels - `label` slot: used for custom HTML labels -- `aria-label`: used for selects with no visible label +- `aria-label`: used to provide a label for screen readers but adds no visible label ### Label Placement @@ -50,7 +52,7 @@ import LabelSlot from '@site/static/usage/v7/select/label-slot/index.md'; ### No Visible Label -If no visible label is needed, devs should still supply an `aria-label` so the select is accessible to screen readers. +If no visible label is needed, developers should still supply an `aria-label` so the select is accessible to screen readers. import NoVisibleLabel from '@site/static/usage/v7/select/no-visible-label/index.md'; diff --git a/static/usage/v7/input/label-slot/angular.md b/static/usage/v7/input/label-slot/angular.md new file mode 100644 index 00000000000..21bdbf74b64 --- /dev/null +++ b/static/usage/v7/input/label-slot/angular.md @@ -0,0 +1,9 @@ +```html + + + +
Email (Required)
+ + + +``` diff --git a/static/usage/v7/input/label-slot/demo.html b/static/usage/v7/input/label-slot/demo.html new file mode 100644 index 00000000000..234aa3cbec3 --- /dev/null +++ b/static/usage/v7/input/label-slot/demo.html @@ -0,0 +1,28 @@ + + + + + + input + + + + + + + + + +
+ + + +
Email (Required)
+ + + +
+ + + + diff --git a/static/usage/v7/input/label-slot/index.md b/static/usage/v7/input/label-slot/index.md new file mode 100644 index 00000000000..24328d5cd70 --- /dev/null +++ b/static/usage/v7/input/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/input/label-slot/javascript.md b/static/usage/v7/input/label-slot/javascript.md new file mode 100644 index 00000000000..494d85ba6cb --- /dev/null +++ b/static/usage/v7/input/label-slot/javascript.md @@ -0,0 +1,9 @@ +```html + + + +
Email (Required)
+ + + +``` diff --git a/static/usage/v7/input/label-slot/react.md b/static/usage/v7/input/label-slot/react.md new file mode 100644 index 00000000000..d4bc7902935 --- /dev/null +++ b/static/usage/v7/input/label-slot/react.md @@ -0,0 +1,17 @@ +```tsx +import React from 'react'; +import { IonInput, IonItem, IonList, IonText } from '@ionic/react'; + +function Example() { + return ( + + + +
Email (Required)
+ + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/input/label-slot/vue.md b/static/usage/v7/input/label-slot/vue.md new file mode 100644 index 00000000000..4b3fb3daeb8 --- /dev/null +++ b/static/usage/v7/input/label-slot/vue.md @@ -0,0 +1,20 @@ +```html + + + +``` diff --git a/static/usage/v7/input/no-visible-label/angular.md b/static/usage/v7/input/no-visible-label/angular.md new file mode 100644 index 00000000000..32616a6a196 --- /dev/null +++ b/static/usage/v7/input/no-visible-label/angular.md @@ -0,0 +1,7 @@ +```html + + + + + +``` diff --git a/static/usage/v7/input/no-visible-label/demo.html b/static/usage/v7/input/no-visible-label/demo.html new file mode 100644 index 00000000000..b8155e10e6f --- /dev/null +++ b/static/usage/v7/input/no-visible-label/demo.html @@ -0,0 +1,26 @@ + + + + + + input + + + + + + + + + +
+ + + + + +
+ + + + diff --git a/static/usage/v7/input/no-visible-label/index.md b/static/usage/v7/input/no-visible-label/index.md new file mode 100644 index 00000000000..de0fe522748 --- /dev/null +++ b/static/usage/v7/input/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/input/no-visible-label/javascript.md b/static/usage/v7/input/no-visible-label/javascript.md new file mode 100644 index 00000000000..32616a6a196 --- /dev/null +++ b/static/usage/v7/input/no-visible-label/javascript.md @@ -0,0 +1,7 @@ +```html + + + + + +``` diff --git a/static/usage/v7/input/no-visible-label/react.md b/static/usage/v7/input/no-visible-label/react.md new file mode 100644 index 00000000000..38842ecb0b6 --- /dev/null +++ b/static/usage/v7/input/no-visible-label/react.md @@ -0,0 +1,15 @@ +```tsx +import React from 'react'; +import { IonInput, IonItem, IonList } from '@ionic/react'; + +function Example() { + return ( + + + + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/input/no-visible-label/vue.md b/static/usage/v7/input/no-visible-label/vue.md new file mode 100644 index 00000000000..cc181047943 --- /dev/null +++ b/static/usage/v7/input/no-visible-label/vue.md @@ -0,0 +1,18 @@ +```html + + + +```