ionic-team · liamdebeasi · Jun 20, 2023 · Jun 14, 2023 · Jun 14, 2023 · Jun 14, 2023
diff --git a/docs/api/input.md b/docs/api/input.md
@@ -36,15 +36,41 @@ import Types from '@site/static/usage/v7/input/types/index.md';
 
 <Types />
 
+## Labels
 
-## Label Placement
+Input has several options for supplying a label for the component:
+
+- `label` property: used for plaintext labels
+- `label` slot: used for custom HTML labels (experimental)
+- `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.
 
 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, devs 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
 

diff --git a/static/usage/v7/input/label-slot/angular.md b/static/usage/v7/input/label-slot/angular.md
@@ -0,0 +1,9 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-input labelPlacement="floating" value="hi@ionic.io">
+      <div slot="label">Email <ion-text color="danger">(Required)</ion-text></div>
+    </ion-input>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/input/label-slot/demo.html b/static/usage/v7/input/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>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.0.11-dev.11686769094.1eb95367/dist/ionic/ionic.esm.js"></script>
+    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ionic/core@7.0.11-dev.11686769094.1eb95367/css/ionic.bundle.css" />
+  </head>
+
+  <body>
+    <ion-app>
+      <ion-content>
+        <div class="container">
+          <ion-list>
+            <ion-item>
+              <ion-input label-placement="floating" value="hi@ionic.io">
+                <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>
diff --git a/static/usage/v7/input/label-slot/index.md 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';
+
+<Playground
+  version="7"
+  code={{ javascript, react, vue, angular }}
+  src="usage/v7/input/label-slot/demo.html"
+/>
diff --git a/static/usage/v7/input/label-slot/javascript.md b/static/usage/v7/input/label-slot/javascript.md
@@ -0,0 +1,9 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-input label-placement="floating" value="hi@ionic.io">
+      <div slot="label">Email <ion-text color="danger">(Required)</ion-text></div>
+    </ion-input>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/input/label-slot/react.md 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 (
+    <IonList>
+      <IonItem>
+        <IonInput labelPlacement="floating" value="hi@ionic.io">
+          <div slot="label">Email <IonText color="danger">(Required)</IonText></div>
+        </IonInput>
+      </IonItem>
+    </IonList>
+  );
+}
+export default Example;
+```
diff --git a/static/usage/v7/input/label-slot/vue.md b/static/usage/v7/input/label-slot/vue.md
@@ -0,0 +1,20 @@
+```html
+<template>
+  <ion-list>
+    <ion-item>
+      <ion-input label-placement="floating" value="hi@ionic.io">
+        <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>
+```
diff --git a/static/usage/v7/input/no-visible-label/angular.md b/static/usage/v7/input/no-visible-label/angular.md
@@ -0,0 +1,7 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-input aria-label="Email" value="hi@ionic.io"></ion-input>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/input/no-visible-label/demo.html b/static/usage/v7/input/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>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="hi@ionic.io"></ion-input>
+            </ion-item>
+          </ion-list>
+        </div>
+      </ion-content>
+    </ion-app>
+  </body>
+</html>
diff --git a/static/usage/v7/input/no-visible-label/index.md 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';
+
+<Playground
+  version="7"
+  code={{ javascript, react, vue, angular }}
+  src="usage/v7/input/no-visible-label/demo.html"
+/>
diff --git a/static/usage/v7/input/no-visible-label/javascript.md b/static/usage/v7/input/no-visible-label/javascript.md
@@ -0,0 +1,7 @@
+```html
+<ion-list>
+  <ion-item>
+    <ion-input aria-label="Email" value="hi@ionic.io"></ion-input>
+  </ion-item>
+</ion-list>
+```
diff --git a/static/usage/v7/input/no-visible-label/react.md 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 (
+    <IonList>
+      <IonItem>
+        <IonInput aria-label="Email" value="hi@ionic.io"></IonInput>
+      </IonItem>
+    </IonList>
+  );
+}
+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
@@ -0,0 +1,18 @@
+```html
+<template>
+  <ion-list>
+    <ion-item>
+      <ion-input aria-label="Email" value="hi@ionic.io"></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>
+```