import Props from '@ionic-internal/component-api/v8/range/props.md'; import Events from '@ionic-internal/component-api/v8/range/events.md'; import Methods from '@ionic-internal/component-api/v8/range/methods.md'; import Parts from '@ionic-internal/component-api/v8/range/parts.md'; import CustomProps from '@ionic-internal/component-api/v8/range/custom-props.mdx'; import Slots from '@ionic-internal/component-api/v8/range/slots.md';

import EncapsulationPill from '@components/page/api/EncapsulationPill';

The Range slider lets users select from a range of values by moving the slider knob. By default one knob controls the value of the range. This behavior can be customized using dual knobs.

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.

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 to provide a label for screen readers but adds no visible label

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/v8/range/labels/index.md';

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/v8/range/label-slot/index.md';

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/v8/range/no-visible-label/index.md';

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.

If the directionality of the document is set to left to right, the contents slotted to the start position will display to the left of the range, where as contents slotted to the end position will display to the right of the range. In right to left (rtl) directionality, the contents slotted to the start position will display to the right of the range, where as contents slotted to the end position will display to the left of the range.

import DecorationsPlayground from '@site/static/usage/v8/range/slots/index.md';

Dual knobs introduce two knob controls that users can use to select a value at a lower and upper bounds. When selected, the Range will emit an ionChange event with a RangeValue, containing the upper and lower values selected.

import DualKnobs from '@site/static/usage/v8/range/dual-knobs/index.md';

The pin attribute will display the value of the Range above the knob when dragged. This allows users to select a specific value within the Range.

With the pinFormatter function, developers can customize the formatting of the range value to the user.

import Pins from '@site/static/usage/v8/range/pins/index.md';

Ticks show indications for each available value on the Range. In order to use ticks, developers must set both snaps and the ticks property to true.

With snapping enabled, the Range knob will snap to the nearest available value as the knob is dragged and released.

import SnappingTicks from '@site/static/usage/v8/range/snapping-ticks/index.md';

The ionChange event emits as the Range knob value changes.

import IonChangeEvent from '@site/static/usage/v8/range/ion-change-event/index.md';

The ionKnobMoveStart event emits when the Range knob begins dragging, whether through mouse drag, touch gesture or keyboard interaction. Inversely, ionKnobMoveEnd emits when the Range knob is released. Both events emit with the RangeValue type and work in combination with the dualKnobs property.

import IonKnobMoveEvent from '@site/static/usage/v8/range/ion-knob-move-event/index.md';

Range includes CSS Variables to quickly theme and customize the appearance of the Range component to match your application's design.

import CSSProps from '@site/static/usage/v8/range/theming/css-properties/index.md';

Range includes CSS Shadow Parts to allow complete customization of specific element nodes within the Range component. CSS Shadow Parts offer the most customization capabilities and are the recommended approach when requiring advance styling with the Range component.

import CSSParts from '@site/static/usage/v8/range/theming/css-shadow-parts/index.md';

A simpler range syntax was introduced in Ionic 7.0. This new syntax reduces the boilerplate required to setup an range, resolves accessibility issues, and improves the developer experience.

Developers can perform this migration one range at a time. While developers can continue using the legacy syntax, we recommend migrating as soon as possible.

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/v8/range/migration/index.md';

:::note In past versions of Ionic, ion-item was required for ion-range to function properly. Starting in Ionic 7.0, ion-range should only be used in an ion-item when the item is placed in an ion-list. Additionally, ion-item is no longer required for ion-range to function properly. :::

Ionic uses heuristics to detect if an app is using the modern range syntax. In some instances, it may be preferable to continue using the legacy syntax. Developers can set the legacy property on ion-range to true to force that instance of the range to use the legacy syntax.

interface RangeChangeEventDetail {
  value: RangeValue;
}

interface RangeKnobMoveStartEventDetail {
  value: RangeValue;
}

interface RangeKnobMoveEndEventDetail {
  value: RangeValue;
}

While not required, this interface can be used in place of the CustomEvent interface for stronger typing with Ionic events emitted from this component.

interface RangeCustomEvent extends CustomEvent {
  detail: RangeChangeEventDetail;
  target: HTMLIonRangeElement;
}

type RangeValue = number | { lower: number, upper: number };