The header
is a toolbar at the top of the page that usually contains the page title text and optional buttons positioned to the the left and/or right of the title for navigation or actions.
The title text is normally an H1 heading element but it's possible to use any heading level (H1-H6) to allow for semantic flexibility. For example, a page containing multiple mobile 'pages' may use a H1 element on the home 'page' and a H2 element on the secondary pages. All heading levels are styled identically by default to maintain visual consistency.
<div data-role="header">
<h1>Page Title</h1>
</div>
The header
toolbar is themed with the "a" swatch by default (black in the default theme) but you can easily set the theme swatch color.
See that "back" button? The framework automatically generates a "back" button on every page, to simplify the process of including this common navigation element. To prevent the back button from being added to a header, either add your own button to the left slot (see below) or, add this attribute: data-backbtn="false"
to the header container.
In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an anchor
element, but any valid button markup will work. To save space, buttons in toolbars are set to inline styling so the button is only as wide as the text and icons it contains.
If you use the attribute data-rel="back"
on an anchor, any clicks on that anchor will mimic the back button, going back one history entry and ignoring the anchor's default href. This is particularly useful when linking back to a named page, such as a link that says "home", or when generating "back" buttons with JavaScript, such as a button to close a dialog. When using this feature in your source markup, be sure to provide a meaningful href that actually points to the URL of the referring page (this will allow the feature to work for users in C-Grade browsers. Also, pease keep in mind that if you just want a reverse transition without actually going back in history, you should use the data-direction="reverse"
attribute instead.
The header plugin looks for immediate children of the header container, and automatically sets the first link in the left button slot and the second link in the right. In this example, the 'Cancel' button will appear in the left slot and 'Save' will appear in the right slot based on their sequence in the source order.
<div data-role="header" data-position="inline">
<a href="index.html" data-icon="delete">Cancel</a>
<h1>Edit Contact</h1>
<a href="index.html" data-icon="check">Save</a>
</div>
Buttons automatically adopt the swatch color of the bar they sit in, so a link in a header bar with the "a" color will also be styled as "a" colored buttons. It's simple to make a button visually stand out — here, we add the data-theme
attribute and set the color swatch for the button to "b" to make the "Save" button pop.
<div data-role="header" data-position="inline">
<a href="index.html" data-icon="delete">Cancel</a>
<h1>Edit Contact</h1>
<a href="index.html" data-icon="check" data-theme="b">Save</a>
</div>
The button position can also be controlled by adding classes to the button anchors, rather than relying on source order. This is especially useful if you only want a button in the right slot. To specify the button position, add the class of ui-btn-left
or ui-btn-right
to the anchor.
In this example, we're adding only a single button to the right slot so the data-backbtn="false"
needs to be added to the header container to suppress the automatic Back button behavior and the button needs the ui-btn-right
class on the link.
<div data-role="header" data-position="inline" data-backbtn="false">
<h1>Page Title</h1>
<a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
</div>
If you'd like to configure the back button text, you can either use the data-back-btn-text="previous"
attribute on your page element, or set it programmatically via the page plugin's options: $.mobile.page.prototype.options.backBtnText = "previous";
.
If you'd like to configure the back button role-theme, you can use: $.mobile.page.prototype.options.backBtnTheme = "a";
.
If you're doing this programmatically, set this option inside the mobileinit event handler.
If you need to to create a header that doesn't follow the default configuration, simply wrap your custom styled markup in a container div
inside the header container and the plugin won't apply the automatic button logic so you can write custom styles for laying out the content in your header.