Pull to refresh

The <ons-pull-hook> is used to perform an action when the user pulls down the page. It’s a common design pattern in mobile apps.

It is normally put as a direct descendant to the <ons-page> element.

<ons-page>
  <ons-toolbar>
    ...
  </ons-toolbar>

  <ons-pull-hook></ons-pull-hook>
</ons-page>

Setting the callback

To set the callback that should be executed when the user pulls the page you can modify the onAction property.

The callback will take a function as an argument that needs to be called when the action is performed. Calling the function will cause the page to snap back into position.

var pullHook = document.getElementById('pull-hook');
pullHook.onAction = function(done) {
  refreshTheData()
    .then(done);
};

States

The <ons-pull-hook> has three different states:

• initial - Initial state.
• preaction - Will run the callback when released.
• action - Currently running the callback.

The element will throw the DOM event changestate when it transitions between any of these states.

pullHook.addEventListener('changestate', function(event) {
  console.log('Changed to state: ' + event.state);
});

Listening to these state changes can be used to change the content of the element to give the user information about what is happening.

Styling with CSS

Another way to change the content or the appearance of the <ons-pull-hook> element is to use CSS and attribute selectors.

The element has the attribute style which will have the value of the current state:

ons-pull-hook[style="initial"] {
  // Write some style for initial state here.
}

...

Customizing the behavior

There are a number of attributes that can be used to configure how the <ons-pull-hook> will behave.

The height attribute defines how long the component must be pulled before transitioning to the preaction state. With the threshold-height attribute the component can be configured to transition directly to the action state without releasing.

There is also an attribute called fixed-content that prevents the page from moving while scrolling.

Additionally, the onPull DOM prop provides a way to gradually modify the appearance of the pull-hook when the user pulls it. This could be useful, for example, to place a <ons-progress-circular> element as the visual part of <ons-pull-hook> and change its progress value as the user pulls.