Skip to main content
Version: v7

ion-range

shadow

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

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

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.

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.

No Visible Label

If no visible label is needed, developers should still supply an aria-label so the range is accessible to screen readers.

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.

Console
Console messages will appear here when logged from the example above.

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.

Console
Console messages will appear here when logged from the example above.

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 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.

<!-- Basic -->

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

<!-- After -->
<ion-item>
<ion-range label="Notifications"></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" label="Notifications"></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" label="Notifications"></ion-range>
</ion-item>

<!-- Custom HTML label -->

<!-- Before -->
<ion-item>
<ion-label>
<div class="custom-label">Notifications</div>
</ion-label>
<ion-range></ion-range>
</ion-item>

<!-- After -->
<ion-item>
<ion-range>
<div slot="label" class="custom-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

DescriptionThe 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.
Attributeactive-bar-start
Typenumber | undefined
Defaultundefined

color

DescriptionThe 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.
Attributecolor
Type"danger" | "dark" | "light" | "medium" | "primary" | "secondary" | "success" | "tertiary" | "warning" | string | undefined
Defaultundefined

debounce

DescriptionHow long, in milliseconds, to wait to trigger the ionInput event after each change in the range value.
Attributedebounce
Typenumber | undefined
Defaultundefined

disabled

DescriptionIf true, the user cannot interact with the range.
Attributedisabled
Typeboolean
Defaultfalse

dualKnobs

DescriptionShow two knobs.
Attributedual-knobs
Typeboolean
Defaultfalse

label

DescriptionThe text to display as the control's label. Use this over the label slot if you only need plain text. The label property will take priority over the label slot if both are used.
Attributelabel
Typestring | undefined
Defaultundefined

labelPlacement

DescriptionWhere to place the label relative to the range. "start": The label will appear to the left of the range in LTR and to the right in RTL. "end": The label will appear to the right of the range in LTR and to the left in RTL. "fixed": The label has the same behavior as "start" except it also has a fixed width. Long text will be truncated with ellipses ("..."). "stacked": The label will appear above the range regardless of the direction.
Attributelabel-placement
Type"end" | "fixed" | "stacked" | "start"
Default'start'

legacy

DescriptionSet the legacy property to true to forcibly use the legacy form control markup. Ionic will only opt components in to the modern form markup when they are using either the aria-label attribute or the label property. As a result, the legacy property should only be used as an escape hatch when you want to avoid this automatic opt-in behavior. Note that this property will be removed in an upcoming major release of Ionic, and all form components will be opted-in to using the modern form markup.
Attributelegacy
Typeboolean | undefined
Defaultundefined

max

DescriptionMaximum integer value of the range.
Attributemax
Typenumber
Default100

min

DescriptionMinimum integer value of the range.
Attributemin
Typenumber
Default0

mode

DescriptionThe mode determines which platform styles to use.
Attributemode
Type"ios" | "md"
Defaultundefined

name

DescriptionThe name of the control, which is submitted with the form data.
Attributename
Typestring
Defaultthis.rangeId

pin

DescriptionIf true, a pin with integer value is shown when the knob is pressed.
Attributepin
Typeboolean
Defaultfalse

pinFormatter

DescriptionA callback used to format the pin text. By default the pin text is set to Math.round(value).

See https://ionicframework.com/docs/troubleshooting/runtime#accessing-this if you need to access this from within the callback.
Attributeundefined
Type(value: number) => string | number
Default(value: number): number => Math.round(value)

snaps

DescriptionIf true, the knob snaps to tick marks evenly spaced based on the step property value.
Attributesnaps
Typeboolean
Defaultfalse

step

DescriptionSpecifies the value granularity.
Attributestep
Typenumber
Default1

ticks

DescriptionIf true, tick marks are displayed based on the step value. Only applies when snaps is true.
Attributeticks
Typeboolean
Defaulttrue

value

Descriptionthe value of the range.
Attributevalue
Typenumber | { lower: number; upper: number; }
Default0

Events

NameDescriptionBubbles
ionBlurEmitted when the range loses focus.true
ionChangeThe ionChange event is fired for <ion-range> elements when the user modifies the element's value: - When the user releases the knob after dragging; - When the user moves the knob with keyboard arrows

ionChange is not fired when the value is changed programmatically.
true
ionFocusEmitted when the range has focus.true
ionInputThe ionInput event is fired for <ion-range> elements when the value is modified. Unlike ionChange, ionInput is fired continuously while the user is dragging the knob.true
ionKnobMoveEndEmitted when the user finishes moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction.true
ionKnobMoveStartEmitted when the user starts moving the range knob, whether through mouse drag, touch gesture, or keyboard interaction.true

Methods

No public methods available for this component.

CSS Shadow Parts

NameDescription
barThe inactive part of the bar.
bar-activeThe active part of the bar.
knobThe handle that is used to drag the range.
labelThe label text describing the range.
pinThe counter that appears above a knob.
tickAn inactive tick mark.
tick-activeAn active tick mark.

CSS Custom Properties

NameDescription
--bar-backgroundBackground of the range bar
--bar-background-activeBackground of the active range bar
--bar-border-radiusBorder radius of the range bar
--bar-heightHeight of the range bar
--heightHeight of the range
--knob-backgroundBackground of the range knob
--knob-border-radiusBorder radius of the range knob
--knob-box-shadowBox shadow of the range knob
--knob-sizeSize of the range knob
--pin-backgroundBackground of the range pin (only available in MD mode)
--pin-colorColor of the range pin (only available in MD mode)

Slots

NameDescription
endContent is placed to the right of the range slider in LTR, and to the left in RTL.
labelThe label text to associate with the range. Use the "labelPlacement" property to control where the label is placed relative to the range.
startContent is placed to the left of the range slider in LTR, and to the right in RTL.