Refresher

ion-refresher

Improve this doc

The Refresher provides pull-to-refresh functionality on a content component. Place the ion-refresher as the first child of your ion-content element.

Pages can then listen to the refresher's various output events. The refresh output event is fired when the user has pulled down far enough to kick off the refreshing process. Once the async operation has completed and the refreshing should end, call complete().

Note: Do not wrap the ion-refresher in a *ngIf. It will not render properly this way. Please use the enabled property instead to display or hide the refresher.

Usage

<ion-content>

  <ion-refresher (ionRefresh)="doRefresh($event)">
    <ion-refresher-content></ion-refresher-content>
  </ion-refresher>

</ion-content>
@Component({...})
export class NewsFeedPage {

  doRefresh(refresher) {
    console.log('Begin async operation', refresher);

    setTimeout(() => {
      console.log('Async operation has ended');
      refresher.complete();
    }, 2000);
  }

}

Refresher Content

By default, Ionic provides the pulling icon and refreshing spinner that looks best for the platform the user is on. However, you can change the default icon and spinner, along with adding text for each state by adding properties to the child ion-refresher-content component.

<ion-content>

  <ion-refresher (ionRefresh)="doRefresh($event)">
    <ion-refresher-content
      pullingIcon="arrow-dropdown"
      pullingText="Pull to refresh"
      refreshingSpinner="circles"
      refreshingText="Refreshing...">
    </ion-refresher-content>
  </ion-refresher>

</ion-content>

Further Customizing Refresher Content

The ion-refresher component holds the refresh logic. It requires a child component in order to display the content. Ionic uses ion-refresher-content by default. This component displays the refresher and changes the look depending on the refresher's state. Separating these components allows developers to create their own refresher content components. You could replace our default content with custom SVG or CSS animations.

Instance Members

state

The current state which the refresher is in. The refresher’s states include:

startY

The Y coordinate of where the user started to the pull down the content.

currentY

The current touch or mouse event’s Y coordinate.

deltaY

The distance between the start of the pull and the current touch or mouse event’s Y coordinate.

progress

A number representing how far down the user has pulled. The number 0 represents the user hasn’t pulled down at all. The number 1, and anything greater than 1, represents that the user has pulled far enough down that when they let go then the refresh will happen. If they let go and the number is less than 1, then the refresh will not happen, and the content will return to it’s original position.

complete()

Call complete() when your async operation has completed. For example, the refreshing state is while the app is performing an asynchronous operation, such as receiving more data from an AJAX request. Once the data has been received, you then call this method to signify that the refreshing has completed and to close the refresher. This method also changes the refresher’s state from refreshing to completing.

cancel()

Changes the refresher’s state from refreshing to cancelling.

Input Properties

Attr Type Details
pullMin number

The min distance the user must pull down until the refresher can go into the refreshing state. Default is 60.

pullMax number

The maximum distance of the pull until the refresher will automatically go into the refreshing state. By default, the pull maximum will be the result of pullMin + 60.

closeDuration number

How many milliseconds it takes to close the refresher. Default is 280.

snapbackDuration number

How many milliseconds it takes the refresher to to snap back to the refreshing state. Default is 280.

enabled boolean

If the refresher is enabled or not. This should be used in place of an ngIf. Default is true.

Output Events

Attr Details
ionRefresh

When the user lets go and has pulled down far enough, which would be farther than the pullMin, then your refresh hander if fired and the state is updated to refreshing. From within your refresh handler, you must call the complete() method when your async operation has completed.

ionPull

While the user is pulling down the content and exposing the refresher.

ionStart

When the user begins to start pulling down.

Sass Variables

All

Property Default Description
$refresher-height 60px

Height of the refresher

$refresher-icon-color #000

Color of the refresher icon

$refresher-icon-font-size 30px

Font size of the refresher icon

$refresher-text-color #000

Text color of the refresher content

$refresher-text-font-size 16px

Font size of the refresher content

$refresher-border-color #ddd

Border color of the refresher

API

Native

General