ons-page

This component defines the root of each page. If the content is large it will become scrollable. A navigation bar can be added to the top of the page using the <ons-toolbar> element.

Tutorial

The page element

The root of a page in Onsen UI is created using the <ons-page> element. It covers the whole screen and is used as a container for the other elements. When managing multiple views, all of them must be contained in <ons-page> element.

<ons-page>
  Content goes here
</ons-page>

This element automatically spawns a background and a content elements. These can also be manually provided for higher customizability:

<ons-page>
  Toolbar here

  <div class="background"></div>

  <div class="content">
    Scrollable content here
  </div>

  Fixed content here
</ons-page>

Since content element is transparent by default, we can add custom colors to the background element. Notice that, if content element is provided, scrollable and fixed content must be manually separated as well. See Compilation section for further details.

Lifecycle

The page element throws init, show, hide and destroy events depending on its lifecycle. The most important one is perhaps init event, where all the page initialization code should be placed:

document.addEventListener('init', function(event) {
  var page = event.target;
  if (page.matches('#myPageID') {
    // Set up page's dynamic content or behavior
    page.querySelector('ons-toolbar .center').innerHTML = 'Title';
    page.querySelector('ons-button').onclick = function() {};
    // ...
  }
});

Alternatively, lifecycle hooks are also provided for those who prefer a more compact approach. onInit, onShow, onHide and onDestroy are run at the same time as their corresponding events. Hooks must be added in a script tag directly inside the page:

<ons-page>
  Content here

  <script>
    ons.getScriptPage().onInit = function() {
      // Hooks are bound to the page element

      this.querySelector('ons-toolbar .center').innerHTML = 'Title';
      this.onShow = function() {};
    };
  </script>
</ons-page>

ons.getScriptPage() returns the page element of the current script tag. It cannot be used in any other context.

Infinite scroll

By using the onInfiniteScroll DOM prop or the on-infinite-scroll attribute we can set an action that will be executed whenever the scroll reaches the bottom of the page. This can be used, for example, to add new items to a list:

document.addEventListener('init', function(event) {
  var page = event.target;

  page.onInfiniteScroll = function(done) {
    var list = page.querySelector('ons-list');

    getNewAsyncData()
      .then(function(data) {

        data.forEach(function(item) {
          var newItem = ons.createElement('<ons-list-item>' + item + '<ons-list-item>');
          list.appendChild(newItem);
        });

        done(); // Important!
      });
  };
});

Note that done callback should be called when the processing is over. If, for some reason, you have asynchronous operations, make sure done runs after everything is finished.

Compilation

There are basically 3 parts inside an ons-page:

  • Background: Applies background color or image.
  • Scrollable content: Scrollable part where most of the content is included.
  • Fixed elements: Content that is fixed in the screen during scroll.

ons-page tries to separate fixed and scrollable content upon creation when these parts are not provided. Specifically, when you create a page like this:

<ons-page>
  <ons-toolbar></ons-toolbar>
  Some content here
  <ons-input></ons-input>
  <ons-fab></ons-fab>
  <div>More content</div>
</ons-page>
`

ons-page will compile in the following way:

<ons-page class="page">
  <ons-toolbar></ons-toolbar>
  <div class="page__background"></div>
  <div class="page__content">
    Some content here
    <ons-input></ons-input>
    <div>More content</div>
  </div>
  <ons-fab></ons-fab>
</ons-page>

As you can see, it added .page, div.page__background and div.page__content automatically. ons-toolbar and ons-fab are fixed content so they are left outside the previous wrappers. If you want to add an extra ons-fab after all of this happens, you should add it as a direct child of ons-page. However, other non-fixed elements like ons-input must be appended inside div.page__content.

Knowing this, it is very easy to bypass the compilation process. If you directly provide the previous structure, Onsen UI won’t need to change anything at all. To make it easier, you can just include <div class="content"> or <div class="background"> and the other necessary classes (page__content and page__background) will be added automatically. Example:

<ons-page>
  <ons-toolbar></ons-toolbar>
  <div class="content">
    Some content here
    <ons-input></ons-input>
    <div>More content</div>
  </div>
  <ons-fab></ons-fab>
</ons-page>

As a side note, the scrollable part of ons-page is precisely div.page__content. Therefore, if you need to add listeners or anything else, you should use the latter.

See also

Attributes

Name Type Description
modifier String Specify modifier name to specify custom styles. Optional.
on-infinite-scroll String Path of the function to be executed on infinite scrolling. Example: app.loadData. The function receives a done callback that must be called when it’s finished. Optional.

Properties

Name Description
onInfiniteScroll Function to be executed when scrolling to the bottom of the page. The function receives a done callback as an argument that must be called when it’s finished.
onDeviceBackButton Back-button handler.
data User’s custom data passed to pushPage()-like methods.

Preset Modifiers

Name Description
material Material Design style

Events

Name Description
init Fired right after the page is attached.
show Fired right after the page is shown.
hide Fired right after the page is hidden.
destroy Fired right before the page is destroyed.
init

Fired right after the page is attached.

Parameters
Name Type Description
event Object Event object.
show

Fired right after the page is shown.

Parameters
Name Type Description
event Object Event object.
hide

Fired right after the page is hidden.

Parameters
Name Type Description
event Object Event object.
destroy

Fired right before the page is destroyed.

Parameters
Name Type Description
event Object Event object.

Discussion

Need Help?

If you have any questions, use our Community Forum or talk to us via Gitter 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.