ons-pull-hook

Component that adds Pull to refresh functionality to an <ons-page> element. It can be used to perform a task when the user pulls down at the top of the page. A common usage is to refresh the data displayed in a page.

Tutorial

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

The callback that should be executed when the user pulls the page can be set as an expression with ng-action attribute: <ons-pull-hook ng-action="myController.load($done)">

This callback will take a $done 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.

app.controller('MyController', function() {
  this.load = function($done) {
    refreshData()
      .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 update its state in pullHook.state property so it can be easily accessed by, for example, ng-switch:

<ons-pull-hook ng-action="page.load($done)" var="pullHook">
  <span ng-switch="pullHookElement.state">
    <span ng-switch-when="initial">Pull down to refresh</span>
    <span ng-switch-when="preaction">Release to refresh</span>
    <span ng-switch-when="action">Loading data...</span>
  </span>
</ons-pull-hook>

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.

Name Type Description
disabled If this attribute is set the “pull-to-refresh” functionality is disabled. Optional.
height String Specify the height of the component. When pulled down further than this value it will switch to the “preaction” state. The default value is “64px”. Optional.
threshold-height String Specify the threshold height. The component automatically switches to the “action” state when pulled further than this value. The default value is “96px”. A negative value will disable this property. If this value is lower than the height, it will skip “preaction” state. Optional.
fixed-content If this attribute is set the content of the page will not move when pulling. Optional.
var String Variable name to refer this component. Optional. Works only during initialization.
ng-action Expression Use to specify custom behavior when the page is pulled down. A $done function is available to tell the component that the action is completed. Optional. Works only during initialization.
ons-changestate Expression Allows you to specify custom behavior when the “changestate” event is fired. Optional. Works only during initialization.
Name Description
fixedContent If this property is set the content of the page will not move when pulling.
onAction This will be called in the action state if it exists. The function will be given a done callback as its first argument.
onPull Hook called whenever the user pulls the element. It gets the pulled distance ratio (scroll / height) and an animationOptions object as arguments.
height The height of the pull hook in pixels. The default value is 64px.
thresholdHeight The thresholdHeight of the pull hook in pixels. The default value is 96px.
state Current state of the element.
pullDistance The current number of pixels the pull hook has moved.
disabled Whether the element is disabled or not.
Signature Description
on(eventName, listener) Add an event listener.
once(eventName, listener) Add an event listener that’s only triggered once.
off(eventName, [listener]) Remove an event listener. If the listener is not specified all listeners for the event type will be removed.
on(eventName, listener)

Add an event listener.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.
once(eventName, listener)

Add an event listener that’s only triggered once.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.
off(eventName, [listener])

Remove an event listener. If the listener is not specified all listeners for the event type will be removed.

Parameters
Name Type Description
eventName String Name of the event.
listener Function Function to execute when the event is triggered.

Some Onsen UI components have overlapping event names. For example, ons-carousel and ons-navigator both emit postchange events. Stop overlapping events from propagating to avoid conflicts: document.querySelector('ons-carousel').on('postchange', e => e.stopPropagation()).

Name Description
changestate Fired when the state is changed. The state can be either “initial”, “preaction” or “action”.
pull Fired when the pull hook is pulled.
changestate

Fired when the state is changed. The state can be either “initial”, “preaction” or “action”.

Parameters
Name Type Description
event Object Event object.
event.pullHook Object Component object.
event.state String Current state.
pull

Fired when the pull hook is pulled.

Parameters
Name Type Description
event Object Event object.
event.ratio Object The pulled distance ratio (scroll / height).
event.animationOptions String The animation options object.

Need Help?

If you have any questions, use our Community Forum or talk to us on Discord chat. The Onsen UI team and your peers in the community will work together to help solve your issues.

For bug reports and feature requests use our GitHub Issues page.