Version: v7 (beta)

ion-range

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.

Basic Usage

Label Placement

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.

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.

Dual Knobs

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.

Pins

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.

Snapping & Ticks

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.

Event Handling

Using `ionChange`

The ionChange event emits as the Range knob value changes.

Using `ionKnobMoveStart` and `ionKnobMoveEnd`

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.

Theming

CSS Custom Properties

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

CSS Shadow Parts

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.

Migrating from Legacy Range Syntax

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

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.

JavaScript
Angular
React
Vue

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range>
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="fixed">
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Range at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="end">
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range>
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range labelPlacement="fixed">
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Range at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range labelPlacement="end">
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

{/* Basic */}

{/* Before */}
<IonItem>
  <IonLabel>Notifications</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* After */}
<IonItem>
  <IonRange>
    <div slot="label">Notifications</div>
  </IonRange>
</IonItem>

{/* Fixed Labels */}

{/* Before */}
<IonItem>
  <IonLabel position="fixed">Notifications</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* After */}
<IonItem>
  <IonRange labelPlacement="fixed">
    <div slot="label">Notifications</div>
  </IonRange>
</IonItem>

{/* Range at the start of line, Label at the end of line */}

{/* Before */}
<IonItem>
  <IonLabel slot="end">Notifications</IonLabel>
  <IonRange></IonRange>
</IonItem>

{/* After */}
<IonItem>
  <IonRange labelPlacement="end">
    <div slot="label">Notifications</div>
  </IonRange>
</IonItem>

<!-- Basic -->

<!-- Before -->
<ion-item>
  <ion-label>Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range>
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Fixed Labels -->

<!-- Before -->
<ion-item>
  <ion-label position="fixed">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="fixed">
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

<!-- Range at the start of line, Label at the end of line -->

<!-- Before -->
<ion-item>
  <ion-label slot="end">Notifications</ion-label>
  <ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
  <ion-range label-placement="end">
    <div slot="label">Notifications</div>
  </ion-range>
</ion-item>

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.

Using the Legacy Syntax

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.

Interfaces

RangeChangeEventDetail

interface RangeChangeEventDetail {
  value: RangeValue;
}

RangeKnobMoveStartEventDetail

interface RangeKnobMoveStartEventDetail {
  value: RangeValue;
}

RangeKnobMoveEndEventDetail

interface RangeKnobMoveEndEventDetail {
  value: RangeValue;
}

RangeCustomEvent

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;
}

Types

RangeValue

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

Properties

activeBarStart

Description	The start position of the range active bar. This feature is only available with a single knob (dualKnobs="false"). Valid values are greater than or equal to the min value and less than or equal to the max value.
Attribute	`active-bar-start`
Type	`number ｜ undefined`
Default	`undefined`

color

Description	The color to use from your application's color palette. Default options are: `"primary"`, `"secondary"`, `"tertiary"`, `"success"`, `"warning"`, `"danger"`, `"light"`, `"medium"`, and `"dark"`. For more information on colors, see theming.
Attribute	`color`
Type	`"danger" ｜ "dark" ｜ "light" ｜ "medium" ｜ "primary" ｜ "secondary" ｜ "success" ｜ "tertiary" ｜ "warning" ｜ string & Record<never, never> ｜ undefined`
Default	`undefined`

debounce

Description	How long, in milliseconds, to wait to trigger the `ionChange` event after each change in the range value. This also impacts form bindings such as `ngModel` or `v-model`.
Attribute	`debounce`
Type	`number`
Default	`0`

disabled

Description	If `true`, the user cannot interact with the range.
Attribute	`disabled`
Type	`boolean`
Default	`false`

dualKnobs

Description	Show two knobs.
Attribute	`dual-knobs`
Type	`boolean`
Default	`false`

max

Description	Maximum integer value of the range.
Attribute	`max`
Type	`number`
Default	`100`

min

Description	Minimum integer value of the range.
Attribute	`min`
Type	`number`
Default	`0`

mode

Description	The mode determines which platform styles to use.
Attribute	`mode`
Type	`"ios" ｜ "md"`
Default	`undefined`

name

Description	The name of the control, which is submitted with the form data.
Attribute	`name`
Type	`string`
Default	`''`

Description	If `true`, a pin with integer value is shown when the knob is pressed.
Attribute	`pin`
Type	`boolean`
Default	`false`

pinFormatter

Description	A callback used to format the pin text. By default the pin text is set to `Math.round(value)`.
Attribute	`undefined`
Type	`(value: number) => string ｜ number`
Default	`(value: number): number => Math.round(value)`

snaps

Description	If `true`, the knob snaps to tick marks evenly spaced based on the step property value.
Attribute	`snaps`
Type	`boolean`
Default	`false`

step

Description	Specifies the value granularity.
Attribute	`step`
Type	`number`
Default	`1`

ticks

Description	If `true`, tick marks are displayed based on the step value. Only applies when `snaps` is `true`.
Attribute	`ticks`
Type	`boolean`
Default	`true`

value

Description	the value of the range.
Attribute	`value`
Type	`number ｜ { lower: number; upper: number; }`
Default	`0`

Events

Name	Description
`ionBlur`	Emitted when the range loses focus.
`ionChange`	Emitted when the value property has changed.
`ionFocus`	Emitted when the range has focus.
`ionKnobMoveEnd`	Emitted when the user finishes moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction.
`ionKnobMoveStart`	Emitted when the user starts moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction.

Methods

No public methods available for this component.

CSS Shadow Parts

Name	Description
`bar`	The inactive part of the bar.
`bar-active`	The active part of the bar.
`knob`	The handle that is used to drag the range.
`pin`	The counter that appears above a knob.
`tick`	An inactive tick mark.
`tick-active`	An active tick mark.

CSS Custom Properties

Name	Description
`--bar-background`	Background of the range bar
`--bar-background-active`	Background of the active range bar
`--bar-border-radius`	Border radius of the range bar
`--bar-height`	Height of the range bar
`--height`	Height of the range
`--knob-background`	Background of the range knob
`--knob-border-radius`	Border radius of the range knob
`--knob-box-shadow`	Box shadow of the range knob
`--knob-size`	Size of the range knob
`--pin-background`	Background of the range pin (only available in MD mode)
`--pin-color`	Color of the range pin (only available in MD mode)

Slots

Name	Description
`end`	Content is placed to the right of the range slider in LTR, and to the left in RTL.
`start`	Content is placed to the left of the range slider in LTR, and to the right in RTL.

Basic Usage​

Label Placement​

Decorations​

Dual Knobs​

Pins​

Snapping & Ticks​

Event Handling​

Using ionChange​

Using ionKnobMoveStart and ionKnobMoveEnd​

Theming​

CSS Custom Properties​

CSS Shadow Parts​

Migrating from Legacy Range Syntax​

Using the Modern Syntax​

note

Using the Legacy Syntax​

Interfaces​

RangeChangeEventDetail​

RangeKnobMoveStartEventDetail​

RangeKnobMoveEndEventDetail​

RangeCustomEvent​

Types​

RangeValue​

Properties​

activeBarStart​

color​

debounce​

disabled​

dualKnobs​

max​

min​

mode​

name​

pin​

pinFormatter​

snaps​

step​

ticks​

value​

Events​

Methods​

CSS Shadow Parts​

CSS Custom Properties​

Slots​

Contents

Basic Usage

Label Placement

Decorations

Dual Knobs

Pins

Snapping & Ticks

Event Handling

Using `ionChange`

Using `ionKnobMoveStart` and `ionKnobMoveEnd`

Theming

CSS Custom Properties

CSS Shadow Parts

Migrating from Legacy Range Syntax

Using the Modern Syntax

Using the Legacy Syntax

Interfaces

RangeChangeEventDetail

RangeKnobMoveStartEventDetail

RangeKnobMoveEndEventDetail

RangeCustomEvent

Types

RangeValue

Properties

activeBarStart

color

debounce

disabled

dualKnobs

max

min

mode

name

pin

pinFormatter

snaps

step

ticks

value

Events

Methods

CSS Shadow Parts

CSS Custom Properties

Slots