docs(range): update docs to use label prop (#2955)

ionic-team · May 10, 2023 · 944abce · 944abce
1 parent 01d9c09
commit 944abce
Show file tree

Hide file tree

Showing 19 changed files with 207 additions and 87 deletions.
diff --git a/docs/api/range.md b/docs/api/range.md
@@ -22,18 +22,37 @@ The Range slider lets users select from a range of values by moving the slider k
 
 By default the Range slider has a minimum value of `0` and a maximum value of `100`. This can be configured with the `min` and `max` properties.
 
-## Basic Usage
+## Labels
 
-import Basic from '@site/static/usage/v7/range/basic/index.md';
+Range 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 ranges with no visible label
 
-<Basic />
+### Label Placement
 
-## Label Placement
+The below demo shows how to use the `labelPlacement` property to change the position of the label relative to the range. While the `label` property is used here, `labelPlacement` can also be used with the `label` slot.
 
 import LabelsPlayground from '@site/static/usage/v7/range/labels/index.md';
 
 <LabelsPlayground />
 
+### 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 LabelSlotPlayground from '@site/static/usage/v7/range/label-slot/index.md';
+
+<LabelSlotPlayground />
+
+### No Visible Label
+
+If no visible label is needed, devs 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';
+
+<NoVisibleLabel />
+
 ## Decorations
 
 Decorative elements can be passed into the `start` or `end` slots of the range. This is useful for adding icons such as low volume or high volume icons. Since these elements are decorative, they should not be announced by assistive technology such as screen readers.
@@ -116,7 +135,9 @@ Developers can perform this migration one range at a time. While developers can
 
 ### Using the Modern Syntax
 
-Using the modern syntax involves removing the `ion-label` and passing the label directly inside of `ion-range` using `slot="label"`. The placement of the label can be configured using the `labelPlacement` property on `ion-range`.
+Using the modern syntax involves removing the `ion-label` and passing the label to `ion-range` using the `label` property. The placement of the label can be configured using the `labelPlacement` property.
+
+If custom HTML is needed for the label, it can be passed directly inside the `ion-range` using the `label` slot instead.
 
 import Migration from '@site/static/usage/v7/range/migration/index.md';
 

diff --git a/static/usage/v7/range/label-slot/angular.md b/static/usage/v7/range/label-slot/angular.md
@@ -0,0 +1,7 @@
+```html
+<ion-range>
+ <div slot="label">
+ Label with <ion-text color="primary">custom HTML</ion-text>
+ </div>
+</ion-range>
+```
diff --git a/static/usage/v7/range/label-slot/demo.html b/static/usage/v7/range/label-slot/demo.html
@@ -0,0 +1,31 @@
+<!DOCTYPE html>
+<html lang="en">
+ <head>
+ <meta charset="UTF-8" />
+ <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+ <title>Range</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" />
+ <style>
+ ion-range {
+ max-width: 400px;
+ }
+ </style>
+ </head>
+
+ <body>
+ <ion-app>
+ <ion-content>
+ <div class="container">
+ <ion-range>
+ <div slot="label">
+ Label with <ion-text color="primary">custom HTML</ion-text>
+ </div>
+ </ion-range>
+ </div>
+ </ion-content>
+ </ion-app>
+ </body>
+</html>
diff --git a/static/usage/v7/range/basic/index.md → static/usage/v7/range/label-slot/index.md b/static/usage/v7/range/basic/index.md → static/usage/v7/range/label-slot/index.md
@@ -5,4 +5,4 @@ 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/range/basic/demo.html" />
+<Playground version="7" code={{ javascript, react, vue, angular }} src="usage/v7/range/label-slot/demo.html" />
diff --git a/static/usage/v7/range/label-slot/javascript.md b/static/usage/v7/range/label-slot/javascript.md
@@ -0,0 +1,7 @@
+```html
+<ion-range>
+ <div slot="label">
+ Label with <ion-text color="primary">custom HTML</ion-text>
+ </div>
+</ion-range>
+```
diff --git a/static/usage/v7/range/label-slot/react.md b/static/usage/v7/range/label-slot/react.md
@@ -0,0 +1,14 @@
+```tsx
+import React from 'react';
+import { IonRange, IonText } from '@ionic/react';
+function Example() {
+ return (
+ <IonRange>
+ <div slot="label">
+ Label with <IonText color="primary">custom HTML</IonText>
+ </div>
+ </IonRange>
+ );
+}
+export default Example;
+```
diff --git a/static/usage/v7/range/label-slot/vue.md b/static/usage/v7/range/label-slot/vue.md
@@ -0,0 +1,18 @@
+```html
+<template>
+ <ion-range>
+ <div slot="label">
+ Label with <ion-text color="primary">custom HTML</ion-text>
+ </div>
+ </ion-range>
+</template>
+
+<script lang="ts">
+ import { IonRange, IonText } from '@ionic/vue';
+ import { defineComponent } from 'vue';
+
+ export default defineComponent({
+ components: { IonRange, IonText },
+ });
+</script>
+```
diff --git a/static/usage/v7/range/labels/angular.md b/static/usage/v7/range/labels/angular.md
@@ -1,17 +1,11 @@
 ```html
-<ion-range labelPlacement="start">
- <div slot="label">Label at the Start</div>
-</ion-range>
+<ion-range labelPlacement="start" label="Label at the Start"></ion-range>
 
 <br />
 
-<ion-range labelPlacement="end">
- <div slot="label">Label at the End</div>
-</ion-range>
+<ion-range labelPlacement="end" label="Label at the End"></ion-range>
 
 <br />
 
-<ion-range labelPlacement="fixed">
- <div slot="label">Fixed Width Label</div>
-</ion-range>
+<ion-range labelPlacement="fixed" label="Fixed Width Label"></ion-range>
 ```
diff --git a/static/usage/v7/range/labels/demo.html b/static/usage/v7/range/labels/demo.html
@@ -20,21 +20,15 @@
  <ion-content>
  <div class="container">
  <div class="wrapper">
- <ion-range label-placement="start">
- <div slot="label">Label at the Start</div>
- </ion-range>
-
+ <ion-range label-placement="start" label="Label at the Start"></ion-range>
+
  <br />
-
- <ion-range label-placement="end">
- <div slot="label">Label at the End</div>
- </ion-range>
-
+
+ <ion-range label-placement="end" label="Label at the End"></ion-range>
+
  <br />
-
- <ion-range label-placement="fixed">
- <div slot="label">Fixed Width Label</div>
- </ion-range>
+
+ <ion-range label-placement="fixed" label="Fixed Width Label"></ion-range>
  </div>
  </div>
  </ion-content>

diff --git a/static/usage/v7/range/labels/javascript.md b/static/usage/v7/range/labels/javascript.md
@@ -1,17 +1,11 @@
 ```html
-<ion-range label-placement="start">
- <div slot="label">Label at the Start</div>
-</ion-range>
+<ion-range label-placement="start" label="Label at the Start"></ion-range>
 
 <br />
 
-<ion-range label-placement="end">
- <div slot="label">Label at the End</div>
-</ion-range>
+<ion-range label-placement="end" label="Label at the End"></ion-range>
 
 <br />
 
-<ion-range label-placement="fixed">
- <div slot="label">Fixed Width Label</div>
-</ion-range>
+<ion-range label-placement="fixed" label="Fixed Width Label"></ion-range>
 ```
diff --git a/static/usage/v7/range/labels/react.md b/static/usage/v7/range/labels/react.md
@@ -4,21 +4,15 @@ import { IonRange } from '@ionic/react';
 function Example() {
  return (
  <>
- <IonRange labelPlacement="start">
- <div slot="label">Label at the Start</div>
- </IonRange>
+ <IonRange labelPlacement="start" label="Label at the Start"></IonRange>
 
  <br />
 
- <IonRange labelPlacement="end">
- <div slot="label">Label at the End</div>
- </IonRange>
+ <IonRange labelPlacement="end" label="Label at the End"></IonRange>
 
  <br />
 
- <IonRange labelPlacement="fixed">
- <div slot="label">Fixed Width Label</div>
- </IonRange>
+ <IonRange labelPlacement="fixed" label="Fixed Width Label"></IonRange>
  </>
  );
 }

diff --git a/static/usage/v7/range/labels/vue.md b/static/usage/v7/range/labels/vue.md
@@ -1,20 +1,14 @@
 ```html
 <template>
- <ion-range label-placement="start">
- <div slot="label">Label at the Start</div>
- </ion-range>
+ <ion-range label-placement="start" label="Label at the Start"></ion-range>
 
  <br />
 
- <ion-range label-placement="end">
- <div slot="label">Label at the End</div>
- </ion-range>
+ <ion-range label-placement="end" label="Label at the End"></ion-range>
 
  <br />
 
- <ion-range label-placement="fixed">
- <div slot="label">Fixed Width Label</div>
- </ion-range>
+ <ion-range label-placement="fixed" label="Fixed Width Label"></ion-range>
 </template>
 
 <script lang="ts">