ionic-team · liamdebeasi · Jun 20, 2023 · Jun 20, 2023 · Jun 20, 2023 · Jun 20, 2023
diff --git 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
 
 <NoVisibleLabel />
 
-
-
 ## 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
@@ -29,14 +29,40 @@ import BasicPlayground from '@site/static/usage/v7/textarea/basic/index.md';
 
 <BasicPlayground />
 
-## 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';
 
 <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/textarea/label-slot/index.md';
+
+<LabelSlot />
+
+### 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';
+
+<NoVisibleLabel />
+
 ## 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
@@ -0,0 +1,9 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-textarea labelPlacement="floating" value="Lorem Ipsum">
+      <div slot="label">Comments <ion-text color="danger">(Required)</ion-text></div>
+    </ion-textarea>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/textarea/label-slot/demo.html b/static/usage/v7/textarea/label-slot/demo.html
@@ -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>textarea</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-textarea label-placement="floating" value="Lorem Ipsum">
+                <div slot="label">Comments <ion-text color="danger">(Required)</ion-text></div>
+              </ion-textarea>
+            </ion-item>
+          </ion-list>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v7/textarea/label-slot/index.md 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';
+
+<Playground
+  version="7"
+  code={{ javascript, react, vue, angular }}
+  src="usage/v7/textarea/label-slot/demo.html"
+/>
diff --git a/static/usage/v7/textarea/label-slot/javascript.md b/static/usage/v7/textarea/label-slot/javascript.md
@@ -0,0 +1,9 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-textarea label-placement="floating" value="Lorem Ipsum">
+      <div slot="label">Comments <ion-text color="danger">(Required)</ion-text></div>
+    </ion-textarea>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/textarea/label-slot/react.md 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 (
+    <IonList>
+      <IonItem>
+        <IonTextarea labelPlacement="floating" value="Lorem Ipsum">
+          <div slot="label">Comments <IonText color="danger">(Required)</IonText></div>
+        </IonTextarea>
+      </IonItem>
+    </IonList>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v7/textarea/label-slot/vue.md b/static/usage/v7/textarea/label-slot/vue.md
@@ -0,0 +1,20 @@
+```html
+<template>
+  <ion-list>
+    <ion-item>
+      <ion-textarea label-placement="floating" value="Lorem Ipsum">
+        <div slot="label">Comments <ion-text color="danger">(Required)</ion-text></div>
+      </ion-textarea>
+    </ion-item>
+  </ion-list>
+</template>
+
+<script lang="ts">
+  import { IonTextarea, IonItem, IonList, IonText } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonTextarea, IonItem, IonList, IonText },
+  });
+</script>
+```
diff --git a/static/usage/v7/textarea/no-visible-label/angular.md b/static/usage/v7/textarea/no-visible-label/angular.md
@@ -0,0 +1,7 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-textarea aria-label="Comments" value="Lorem Ipsum"></ion-textarea>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/textarea/no-visible-label/demo.html b/static/usage/v7/textarea/no-visible-label/demo.html
@@ -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>textarea</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-textarea aria-label="Comments" value="Lorem Ipsum"></ion-textarea>
+            </ion-item>
+          </ion-list>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v7/textarea/no-visible-label/index.md 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';
+
+<Playground
+  version="7"
+  code={{ javascript, react, vue, angular }}
+  src="usage/v7/textarea/no-visible-label/demo.html"
+/>
diff --git a/static/usage/v7/textarea/no-visible-label/javascript.md b/static/usage/v7/textarea/no-visible-label/javascript.md
@@ -0,0 +1,7 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-textarea aria-label="Comments" value="Lorem Ipsum"></ion-textarea>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/textarea/no-visible-label/react.md 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 (
+    <IonList>
+      <IonItem>
+        <IonTextarea aria-label="Comments" value="Lorem Ipsum"></IonTextarea>
+      </IonItem>
+    </IonList>
+  );
+}
+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
@@ -0,0 +1,18 @@
+```html
+<template>
+  <ion-list>
+    <ion-item>
+      <ion-textarea aria-label="Comments" value="Lorem Ipsum"></ion-textarea>
+    </ion-item>
+  </ion-list>
+</template>
+
+<script lang="ts">
+  import { IonTextarea, IonItem, IonList } from '@ionic/vue';
+  import { defineComponent } from 'vue';
+
+  export default defineComponent({
+    components: { IonTextarea, IonItem, IonList },
+  });
+</script>
+```