ion-refresher

Refresher provides pull-to-refresh functionality on a content component. The pull-to-refresh pattern lets a user pull down on a list of data in order to retrieve more data.

Data should be modified during the refresher's output events. Once the async operation has completed and the refreshing should end, complete() needs to be called on the refresher.

Basic Usage

Pull Properties

The refresher has several properties for customizing the pull gesture. Set the pullFactor to change the speed of the pull, the pullMin property to change the minimum distance the user must pull down, and the pullMax property to change the maximum distance the user must pull down before the refresher enters the refreshing state.

These properties do not apply when the native refresher is enabled.

Custom Refresher Content

The default icon, spinner, and text can be customized on the refresher content based on whether the state of the refresher is pulling or refreshing.

Setting pullingIcon will disable the native refresher.

Native Refreshers

Both iOS and Android platforms provide refreshers that use properties exposed by their respective devices in order to give pull-to-refresh a fluid, native-like feel.

The iOS and Material Design native refreshers are enabled by default in Ionic. However, the native iOS refresher relies on rubber band scrolling in order to work properly and is only compatible with iOS devices as a result. We provide a fallback refresher for apps running in iOS mode on devices that do not support rubber band scrolling.

The native refresher uses a circular spinner for Material Design, while iOS uses the lines spinner. On iOS, the tick marks will progressively show as the page is pulled down.

Certain refresher properties such as the Pull Properties, closeDuration and snapbackDuration are not compatible because much of the native refreshers are scroll-based. See Properties for more information on unsupported properties.

The native refreshers can be disabled by setting the pullingIcon on the refresher content to any icon or spinner. See the Ionicons and Spinner documentation for accepted values.

Usage with Virtual Scroll

Refresher requires a scroll container to function. When using a virtual scrolling solution, you will need to disable scrolling on the ion-content and indicate which element container is responsible for the scroll container with the .ion-content-scroll-host class target.

Developers should apply the following CSS to the scrollable container. This CSS adds a "rubber band" scrolling effect on iOS which allows the native iOS refresher to work properly:

.ion-content-scroll-host::before,
.ion-content-scroll-host::after {
  position: absolute;
  
  width: 1px;
  height: 1px;
  
  content: "";
}

.ion-content-scroll-host::before {
  bottom: -1px;
}

.ion-content-scroll-host::after {
  top: -1px;
}

Advanced Usage

While the refresher can be used with any type of content, a common use case in native apps is to display a list of data that gets updated on refresh. In the below example, the app generates a list of data and then appends data to the top of the list when the refresh is completed. In a real app, the data would be received and updated after sending a request via a network or database call.

Interfaces

RefresherEventDetail

interface RefresherEventDetail {
  complete(): void;
}

RefresherCustomEvent

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 RefresherCustomEvent extends CustomEvent {
  detail: RefresherEventDetail;
  target: HTMLIonRefresherElement;
}

Properties

closeDuration

Description	リフレッシャーを閉じるのにかかる時間。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。
Attribute	close-duration
Type	string
Default	'280ms'

disabled

Description	trueの場合、リフレッシャーは非表示となる。
Attribute	disabled
Type	boolean
Default	false

mode

Description	modeは、どのプラットフォームのスタイルを使用するかを決定します。 This is a virtual property that is set once during initialization and will not update if you change its value after the initial render.
Attribute	mode
Type	"ios" ｜ "md"
Default	undefined

pullFactor

Description	引きの速さを何倍にするか。引きのアニメーションを遅くするには、1より小さい数値を渡します。引っ張る速度を速くするには、1より大きい数値を渡します。デフォルト値は 1 で、カーソルの速度と同じです。もし負の値が渡された場合、代わりに 1 が係数となります。 例えば例えば、渡された値が 1.2 で、コンテンツが 10 ピクセルでドラッグされた場合、10 ピクセルではなく、12 ピクセルでドラッグされます（20% の増加です）。渡された値が 0.8 の場合、ドラッグされた量はカーソルの移動量より少ない 8 ピクセルとなります。 リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。
Attribute	pull-factor
Type	number
Default	1

pullMax

Description	リフレッシャーが自動的に refreshing 状態になるまでの、引っ張りの最大距離。デフォルトは pullMin + 60 の結果です。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシャーが有効になります。
Attribute	pull-max
Type	number
Default	this.pullMin + 60

pullMin

Description	リフレッシャーが refreshing 状態になるまでに、ユーザが引き下げるべき最小距離。リフレッシャーコンテンツがスピナーを使用する場合は適用されず、ネイティブリフレッシャーが有効になる。
Attribute	pull-min
Type	number
Default	60

snapbackDuration

Description	リフレッシャーが refreshing 状態にスナップバックするのにかかる時間。リフレッシュコンテンツがスピナーを使用している場合は適用されず、ネイティブリフレッシュが有効になります。
Attribute	snapback-duration
Type	string
Default	'280ms'

Events

Name	Description	Bubbles
ionPull	ユーザーがコンテンツを引き下げ、リフレッシャーを露出している間に発行されます。	true
ionRefresh	ユーザーがコンテンツから手を離し、pullMinを越えて下に引いたとき、またはコンテンツを下に引き、pullMaxを越えたときに発行されます。リフレッシャーの状態を refreshing に更新します。非同期処理が完了したら complete() メソッドを呼び出す必要があります。	true
ionStart	ユーザーが引き下げを開始するときに発行されます。	true

Methods

cancel

Description	リフレッシュの状態を refreshing から cancelling に変更します。
Signature	cancel() => Promise<void>

complete

Description	非同期操作が完了したら complete() を呼び出します。例えば、refreshing状態は、アプリがAJAXリクエストからより多くのデータを受信するなど、非同期操作を実行している間です。データを受信したら、このメソッドを呼び出して、リフレッシュが完了したことを示し、リフレッシュャを閉じます。このメソッドは、リフレッシャーの状態を refreshing から completing に変更します。
Signature	complete() => Promise<void>

getProgress

Description	ユーザーがどれだけ下に引っ張られたかを表す数値です。数値 0 は、ユーザーが全く下に引いていないことを表します。数値 1 および 1 より大きい数値は、ユーザーが手を離したときに更新が行われるほど十分に下に引っ張られたことを表します。もしユーザーが手を離し、数値が 1 より小さい場合は、更新は行われず、コンテンツは元の位置に戻ります。
Signature	getProgress() => Promise<number>

CSS Shadow Parts

No CSS shadow parts available for this component.

CSS Custom Properties

No CSS custom properties available for this component.

Slots

No slots available for this component.