Version: v7

ion-range

Rangeスライダは、スライダノブを動かして、ユーザーが値の範囲を選択できるようにするものです。デフォルトでは、1つのノブがレンジの値を制御します。この動作は dual knobs を使ってカスタマイズすることができます。

デフォルトでは、Rangeスライダーの最小値は0、最大値は100です。これは min と max プロパティで設定することができます。

基本的な使い方

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 はユーザーが下限と上限の値を選択するために使用できる2つのknobsコントロールを導入しています。選択されると、Range は選択された上下限の値を含む RangeValue を持つ ionChange イベントを発信します。

ピン

pin 属性は、ドラッグしたときにノブの上にレンジの値を表示します。これにより、ユーザはRange内の特定の値を選択することができます。

pinFormatter 関数を使用すると、開発者はユーザーに対してレンジの値のフォーマットをカスタマイズすることができます。

Snapping & Ticks

TicksはRange 上で利用可能な各値のインジケータを表示します。Ticksを使用するためには、開発者は snaps と ticks プロパティの両方を true に設定する必要があります。

snapsを有効にし、knobをドラッグして放すと、Range knobは最も近い利用可能な値にスナップします。

イベントハンドリング

Using `ionChange`

ionChange イベントはRange knobの値の変更を監視します。

`ionKnobMoveStart` と `ionKnobMoveEnd` を使う

マウスドラッグ、タッチジェスチャー、キーボード操作のいずれであっても、Range knobのドラッグが開始されると ionKnobMoveStart イベントが発行されます。逆に、ionKnobMoveEndはRange knobがリリースされたときに発生します。両イベントは RangeValue タイプで発生し、dualKnobs プロパティと組み合わせて動作します。

テーマ

CSSカスタムプロパティ

Rangeには、アプリケーションのデザインに合わせてRangeコンポーネントの外観を素早くテーマ化してカスタマイズするためのCSS Variablesが含まれています。

CSS Shadow Parts

Rangeには CSS Shadow Parts があり、Rangeコンポーネント内の特定の要素ノードを完全にカスタマイズすることができます。CSS Shadow Partsは最も多くのカスタマイズ機能を提供し、Rangeコンポーネントで高度なスタイリングが必要な場合に推奨されるアプローチです。

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

必須ではありませんが、このコンポーネントから発行される Ionic イベントでより強く型付けを行うために、CustomEvent インターフェースの代わりにこのインターフェースを使用することが可能です。

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

Types

RangeValue

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

プロパティ

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 `ionInput` event after each change in the range value.
Attribute	`debounce`
Type	`number ｜ undefined`
Default	`undefined`

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`

labelPlacement

Description	Where 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 ("...").
Attribute	`label-placement`
Type	`"end" ｜ "fixed" ｜ "start"`
Default	`'start'`

legacy

Description	Set 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.
Attribute	`legacy`
Type	`boolean ｜ undefined`
Default	`undefined`

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	`this.rangeId`

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`

イベント

Name	Description
`ionBlur`	Emitted when the range loses focus.
`ionChange`	The `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.
`ionFocus`	Emitted when the range has focus.
`ionInput`	The `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.
`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.

メソッド

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カスタムプロパティ

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.
`label`	The label text to associate with the range. Use the "labelPlacement" property to control where the label is placed relative to the range.
`start`	Content is placed to the left of the range slider in LTR, and to the right in RTL.

基本的な使い方​

Label Placement​

Decorations​

Dual Knobs​

ピン​

Snapping & Ticks​

イベントハンドリング​

Using ionChange​

ionKnobMoveStart と ionKnobMoveEnd を使う​

テーマ​

CSSカスタムプロパティ​

CSS Shadow Parts​

Migrating from Legacy Range Syntax​

最新の構文の使い方​

note

Using the Legacy Syntax​

Interfaces​

RangeChangeEventDetail​

RangeKnobMoveStartEventDetail​

RangeKnobMoveEndEventDetail​

RangeCustomEvent​

Types​

RangeValue​

プロパティ​

activeBarStart​

color​

debounce​

disabled​

dualKnobs​

labelPlacement​

legacy​

max​

min​

mode​

name​

pin​

pinFormatter​

snaps​

step​

ticks​

value​

イベント​

メソッド​

CSS Shadow Parts​

CSSカスタムプロパティ​

Slots​

Contents

基本的な使い方

Label Placement

Decorations

Dual Knobs

ピン

Snapping & Ticks

イベントハンドリング

Using `ionChange`

`ionKnobMoveStart` と `ionKnobMoveEnd` を使う

テーマ

CSSカスタムプロパティ

CSS Shadow Parts

Migrating from Legacy Range Syntax

最新の構文の使い方

Using the Legacy Syntax

Interfaces

RangeChangeEventDetail

RangeKnobMoveStartEventDetail

RangeKnobMoveEndEventDetail

RangeCustomEvent

Types

RangeValue

プロパティ

activeBarStart

color

debounce

disabled

dualKnobs

labelPlacement

legacy

max

min

mode

name

pin

pinFormatter

snaps

step

ticks

value

イベント

メソッド

CSS Shadow Parts

CSSカスタムプロパティ

Slots