diff --git a/docs/api/select.md b/docs/api/select.md index d5be17b0978..2636e7d04bb 100644 --- a/docs/api/select.md +++ b/docs/api/select.md @@ -24,6 +24,38 @@ A select should be used with child `` elements. If the child If `value` is set on the ``, the selected option will be chosen based on that value. +## Labels + +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 + +### 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. While the `label` property is used here, `labelPlacement` can also be used with the `label` slot. + +import LabelPlacement from '@site/static/usage/v7/select/label-placement/index.md'; + + + +### Label Slot + +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. + +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. + +import NoVisibleLabel from '@site/static/usage/v7/select/no-visible-label/index.md'; + + + ## Single Selection By default, the select allows the user to select only one option. The alert interface presents users with a radio button styled list of options. The select component's value receives the value of the selected option's value. @@ -83,15 +115,6 @@ import UsingCompareWithExample from '@site/static/usage/v7/select/objects-as-val import ObjectValuesAndMultipleSelectionExample from '@site/static/usage/v7/select/objects-as-values/multiple-selection/index.md'; - - -## 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 LabelPlacement from '@site/static/usage/v7/select/label-placement/index.md'; - - ## Justification diff --git a/static/usage/v7/select/label-slot/angular.md b/static/usage/v7/select/label-slot/angular.md new file mode 100644 index 00000000000..93790d050e2 --- /dev/null +++ b/static/usage/v7/select/label-slot/angular.md @@ -0,0 +1,12 @@ +```html + + + +
Favorite Fruit (Required)
+ Apple + Banana + Orange + + + +``` diff --git a/static/usage/v7/select/label-slot/demo.html b/static/usage/v7/select/label-slot/demo.html new file mode 100644 index 00000000000..35f5b7c5efd --- /dev/null +++ b/static/usage/v7/select/label-slot/demo.html @@ -0,0 +1,31 @@ + + + + + + select + + + + + + + + + +
+ + + +
Favorite Fruit (Required)
+ Apple + Banana + Orange + + + +
+ + + + diff --git a/static/usage/v7/select/label-slot/index.md b/static/usage/v7/select/label-slot/index.md new file mode 100644 index 00000000000..1b25e6b83f6 --- /dev/null +++ b/static/usage/v7/select/label-slot/index.md @@ -0,0 +1,13 @@ +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/select/label-slot/javascript.md b/static/usage/v7/select/label-slot/javascript.md new file mode 100644 index 00000000000..93790d050e2 --- /dev/null +++ b/static/usage/v7/select/label-slot/javascript.md @@ -0,0 +1,12 @@ +```html + + + +
Favorite Fruit (Required)
+ Apple + Banana + Orange + + + +``` diff --git a/static/usage/v7/select/label-slot/react.md b/static/usage/v7/select/label-slot/react.md new file mode 100644 index 00000000000..30dd46d7532 --- /dev/null +++ b/static/usage/v7/select/label-slot/react.md @@ -0,0 +1,20 @@ +```tsx +import React from 'react'; +import { IonItem, IonList, IonSelect, IonSelectOption, IonText } from '@ionic/react'; + +function Example() { + return ( + + + +
Favorite Fruit (Required)
+ Apple + Banana + Orange + + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/select/label-slot/vue.md b/static/usage/v7/select/label-slot/vue.md new file mode 100644 index 00000000000..4bdeb67e1d0 --- /dev/null +++ b/static/usage/v7/select/label-slot/vue.md @@ -0,0 +1,23 @@ +```html + + + +``` diff --git a/static/usage/v7/select/no-visible-label/angular.md b/static/usage/v7/select/no-visible-label/angular.md new file mode 100644 index 00000000000..1c14ab03008 --- /dev/null +++ b/static/usage/v7/select/no-visible-label/angular.md @@ -0,0 +1,11 @@ +```html + + + + Apple + Banana + Orange + + + +``` diff --git a/static/usage/v7/select/no-visible-label/demo.html b/static/usage/v7/select/no-visible-label/demo.html new file mode 100644 index 00000000000..12d131e896d --- /dev/null +++ b/static/usage/v7/select/no-visible-label/demo.html @@ -0,0 +1,30 @@ + + + + + + select + + + + + + + + + +
+ + + + Apple + Banana + Orange + + + +
+ + + + diff --git a/static/usage/v7/select/no-visible-label/index.md b/static/usage/v7/select/no-visible-label/index.md new file mode 100644 index 00000000000..214708de577 --- /dev/null +++ b/static/usage/v7/select/no-visible-label/index.md @@ -0,0 +1,13 @@ +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/select/no-visible-label/javascript.md b/static/usage/v7/select/no-visible-label/javascript.md new file mode 100644 index 00000000000..1c14ab03008 --- /dev/null +++ b/static/usage/v7/select/no-visible-label/javascript.md @@ -0,0 +1,11 @@ +```html + + + + Apple + Banana + Orange + + + +``` diff --git a/static/usage/v7/select/no-visible-label/react.md b/static/usage/v7/select/no-visible-label/react.md new file mode 100644 index 00000000000..8695381a487 --- /dev/null +++ b/static/usage/v7/select/no-visible-label/react.md @@ -0,0 +1,19 @@ +```tsx +import React from 'react'; +import { IonItem, IonList, IonSelect, IonSelectOption, IonText } from '@ionic/react'; + +function Example() { + return ( + + + + Apple + Banana + Orange + + + + ); +} +export default Example; +``` diff --git a/static/usage/v7/select/no-visible-label/vue.md b/static/usage/v7/select/no-visible-label/vue.md new file mode 100644 index 00000000000..1d3753d58f8 --- /dev/null +++ b/static/usage/v7/select/no-visible-label/vue.md @@ -0,0 +1,22 @@ +```html + + + +```