Skip to content

docs(input): add label slot and no visible label demos #2997

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Jun 20, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 27 additions & 1 deletion docs/api/input.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,15 +36,41 @@ import Types from '@site/static/usage/v7/input/types/index.md';

<Types />

## 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.

import LabelPlacement from '@site/static/usage/v7/input/label-placement/index.md';

<LabelPlacement />

### 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';

<LabelSlot />

### 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';

<NoVisibleLabel />



## Clear Options

Expand Down
7 changes: 4 additions & 3 deletions docs/api/range.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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';

Expand Down
6 changes: 4 additions & 2 deletions docs/api/select.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,11 +26,13 @@ If `value` is set on the `<ion-select>`, 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

Expand All @@ -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';

Expand Down
9 changes: 9 additions & 0 deletions static/usage/v7/input/label-slot/angular.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
```html
<ion-list>
<ion-item>
<ion-input labelPlacement="floating" value="[email protected]">
<div slot="label">Email <ion-text color="danger">(Required)</ion-text></div>
</ion-input>
</ion-item>
</ion-list>
```
28 changes: 28 additions & 0 deletions static/usage/v7/input/label-slot/demo.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>input</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-list>
<ion-item>
<ion-input label-placement="floating" value="[email protected]">
<div slot="label">Email <ion-text color="danger">(Required)</ion-text></div>
</ion-input>
</ion-item>
</ion-list>
</div>
</ion-content>
</ion-app>
</body>
</html>
12 changes: 12 additions & 0 deletions static/usage/v7/input/label-slot/index.md
Original file line number Diff line number Diff line change
@@ -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';

<Playground
version="7"
code={{ javascript, react, vue, angular }}
src="usage/v7/input/label-slot/demo.html"
/>
9 changes: 9 additions & 0 deletions static/usage/v7/input/label-slot/javascript.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
```html
<ion-list>
<ion-item>
<ion-input label-placement="floating" value="[email protected]">
<div slot="label">Email <ion-text color="danger">(Required)</ion-text></div>
</ion-input>
</ion-item>
</ion-list>
```
17 changes: 17 additions & 0 deletions static/usage/v7/input/label-slot/react.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
```tsx
import React from 'react';
import { IonInput, IonItem, IonList, IonText } from '@ionic/react';

function Example() {
return (
<IonList>
<IonItem>
<IonInput labelPlacement="floating" value="[email protected]">
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The label is not floating in the StackBlitz example

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The StackBlitz examples are using the latest version of Ionic which does not have the slotted label feature. As a result, passing a label to the input will not work as expected. If you manually install the dev build (7.0.11-dev.11686769094.1eb95367) it should work as expected.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh weird that it works for the other frameworks though

<div slot="label">Email <IonText color="danger">(Required)</IonText></div>
</IonInput>
</IonItem>
</IonList>
);
}
export default Example;
```
20 changes: 20 additions & 0 deletions static/usage/v7/input/label-slot/vue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
```html
<template>
<ion-list>
<ion-item>
<ion-input label-placement="floating" value="[email protected]">
<div slot="label">Email <ion-text color="danger">(Required)</ion-text></div>
</ion-input>
</ion-item>
</ion-list>
</template>

<script lang="ts">
import { IonInput, IonItem, IonList, IonText } from '@ionic/vue';
import { defineComponent } from 'vue';

export default defineComponent({
components: { IonInput, IonItem, IonList, IonText },
});
</script>
```
7 changes: 7 additions & 0 deletions static/usage/v7/input/no-visible-label/angular.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
```html
<ion-list>
<ion-item>
<ion-input aria-label="Email" value="[email protected]"></ion-input>
</ion-item>
</ion-list>
```
26 changes: 26 additions & 0 deletions static/usage/v7/input/no-visible-label/demo.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>input</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-list>
<ion-item>
<ion-input aria-label="Email" value="[email protected]"></ion-input>
</ion-item>
</ion-list>
</div>
</ion-content>
</ion-app>
</body>
</html>
12 changes: 12 additions & 0 deletions static/usage/v7/input/no-visible-label/index.md
Original file line number Diff line number Diff line change
@@ -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';

<Playground
version="7"
code={{ javascript, react, vue, angular }}
src="usage/v7/input/no-visible-label/demo.html"
/>
7 changes: 7 additions & 0 deletions static/usage/v7/input/no-visible-label/javascript.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
```html
<ion-list>
<ion-item>
<ion-input aria-label="Email" value="[email protected]"></ion-input>
</ion-item>
</ion-list>
```
15 changes: 15 additions & 0 deletions static/usage/v7/input/no-visible-label/react.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
```tsx
import React from 'react';
import { IonInput, IonItem, IonList } from '@ionic/react';

function Example() {
return (
<IonList>
<IonItem>
<IonInput aria-label="Email" value="[email protected]"></IonInput>
</IonItem>
</IonList>
);
}
export default Example;
```
18 changes: 18 additions & 0 deletions static/usage/v7/input/no-visible-label/vue.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
```html
<template>
<ion-list>
<ion-item>
<ion-input aria-label="Email" value="[email protected]"></ion-input>
</ion-item>
</ion-list>
</template>

<script lang="ts">
import { IonInput, IonItem, IonList } from '@ionic/vue';
import { defineComponent } from 'vue';

export default defineComponent({
components: { IonInput, IonItem, IonList },
});
</script>
```