Toolbar

Toolbars

Headers and footers are elements that precede resp. succeed the page content. The toolbar widget allows you to create headers and footers.

Headers

The header bar serves as the page title, is usually the first element inside each mobile page, and typically contains a page title and up to two buttons.

Header structure

The header is a toolbar at the top of the page that usually contains the page title text and optional buttons positioned to the left and/or right of the title for navigation or actions. Headers can optionally be positioned as fixed so they remain at the top of the screen at all times instead of scrolling with the page.

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>

Default header features

The header toolbar inherits its theme swatch from the page by default but you can easily set the theme swatch color by adding the data-theme attribute to the header. For example, data-theme="b". When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.

Adding buttons

In the standard header configuration, there are slots for buttons on either side of the text heading. Each button is typically an a (anchor) element or a button element that has the attribute data-role="button" set. To save space, buttons in toolbar widgets are set to inline styling so the button is only as wide as the text and icons it contains.

Default button positioning

The toolbar 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">
  <a href="index.html" data-icon="delete">Cancel</a>
  <h1>Edit Contact</h1>
  <a href="index.html" data-icon="check">Save</a>
</div>

Making buttons visually stand out

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 stand out.

<div data-role="header">
  <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>

Controlling button position with classes

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.

<div data-role="header">
  <h1>Page Title</h1>
  <a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
</div>

Adding buttons to toolbar widgets without heading

The heading in the header bar has some margin that will give the bar its height. If you choose not to use a heading, you will need to add an element with class="ui-title" so that the bar can get the height and display correctly.

<div data-role="header">
  <a href="index.html" data-icon="gear" class="ui-btn-right">Options</a>
  <span class="ui-title" />
</div>

Adding Back buttons

jQuery Mobile has a feature to automatically create and append "back" buttons to any header, though it is disabled by default. This is primarily useful in chromeless installed applications, such as those running in a native app webview. The framework automatically generates a "back" button on a header when the toolbar plugin's addBackBtn option is true. This can also be set via markup if the header div has a data-add-back-btn="true" attribute.

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.

If you just want a reverse transition without actually going back in history, you should use the data-direction="reverse" attribute.

Customizing the back button text

If you'd like to configure the back button text, you can either use the data-back-btn-text="previous" attribute on your toolbar element, or set it programmatically via the toolbar plugin's options:
$.mobile.toolbar.prototype.options.backBtnText = "previous";

Default back button style

If you'd like to configure the back button role-theme, you can use:
$.mobile.toolbar.prototype.options.backBtnTheme = "a";
If you're doing this programmatically, set this option inside the mobileinit event handler.

Custom header configurations

If you need to create a header that doesn't follow the default configuration, simply wrap your custom styled markup in any container, such as div. The plugin won't apply the automatic button logic to the wrapped content inside the header container so you can write custom styles for laying out the content in your header.

It's also possible to create custom bars without using the header data-role at all. For example, start with any container and add the ui-bar class to apply standard bar padding and add the ui-bar-b class to assign the bar swatch styles from your theme. (The "b" can be any swatch letter.)

<div class="ui-bar ui-bar-b">
  <h3>I'm just a div with bar classes and a mini inline <a href="#" data-role="button" data-mini="true">Button</a></h3>
</div>

Note that .ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap its contents in an element and apply the padding to that element instead.

By writing some simple styles, it's easy to build message bars like this:

Footers

Footer bar structure

The footer bar has the same basic structure as the header except it uses the data-role attribute value of footer.

<div data-role="footer">
  <h4>Footer content</h4>
</div>

The footer toolbar inherits its theme swatch from the page by default but you can easily set the theme swatch color by adding the data-theme attribute to the header. For example, data-theme="b". When you use external headers you must set a theme, because there is no parent page from which it can inherit a theme.

The page footer is very similar to the header in terms of options and configuration. The primary difference is that the footer is designed to be less structured than the header to allow more flexibility, so the framework doesn't automatically reserve slots for buttons to the left or right as it does in headers.

Since footers do not have the same prescriptive markup conventions as headers, we recommend using layout grids or writing custom styles to achieve the design you want.

Adding buttons

Any link or valid button markup with a data-role="button" attribute added to the footer will automatically be turned into a button. To save space, buttons in toolbar widgets are automatically set to inline styling so the button is only as wide as the text and icons it contains.

By default, toolbar widgets don't have any padding to accommodate nav bars and other widgets. To include padding on the bar, add a class="ui-bar" to the footer.

<div data-role="footer" class="ui-bar">
  <a href="index.html" class="ui-btn ui-corner-all ui-shadow ui-btn-inline ui-btn-icon-right ui-icon-plus">Add</a>
  <a href="index.html" class="ui-btn ui-corner-all ui-shadow ui-btn-inline ui-btn-icon-right ui-icon-arrow-u">Up</a>
  <a href="index.html" class="ui-btn ui-corner-all ui-shadow ui-btn-inline ui-btn-icon-right ui-icon-arrow-d">Down</a>
</div>

This creates this toolbar with buttons sitting in a row

Note that .ui-bar should not be added to header or footer bars that span the full width of the page, as the additional padding will cause a full-width element to break out of its parent container. To add padding inside of a full-width toolbar, wrap the contents of the toolbar widget in an element and apply the padding to that element.

To group buttons together into a button set, wrap the links in a wrapper with data-role="controlgroup" and data-type="horizontal" attributes.

<div data-role="controlgroup" data-type="horizontal">

This creates a grouped set of buttons:

Adding form elements

Form elements and other content can also be added to toolbars. Here is an example of a select menu inside a footer bar. We recommend using mini-sized form elements in toolbars by adding the data-mini="true" attribute:

Fixed & Persistent footers

In situations where the footer is a global navigation element, you may want it to appear fixed so it doesn't scroll out of view. It's also possible to make a fixed toolbar persistent so it appears to not move between page transitions. This can be accomplished by using the persistent footer feature included in jQuery Mobile.

To make a footer persistent between transitions, add the data-id attribute to the footer of all relevant pages and use the same id value for each. For example, by adding data-id="myfooter" to the current page and the target page, the framework will keep the footer anchors in the same spot during the page animation. This effect will only work correctly if the header and footer toolbars are set to data-position="fixed" so they are in view during the transition.

Fixed toolbars

In browsers that support CSS position: fixed (most desktop browsers, iOS5+, Android 2.2+, BlackBerry 6, and others), toolbar widgets that use the "fixedtoolbar" plugin will be fixed to the top or bottom of the viewport, while the page content scrolls freely in between. In browsers that don't support fixed positioning, the toolbars will remain positioned in flow, at the top or bottom of the page.

To enable this behavior on a header or footer, add the data-position="fixed" attribute to a jQuery Mobile toolbar element.

Fixed header markup example:

<div data-role="header" data-position="fixed">
  <h1>Fixed Header</h1>
</div>

Fixed footer markup example:

<div data-role="footer" data-position="fixed">
  <h1>Fixed Footer</h1>
</div>

Note: When you dynamically inject a fixed toolbar into the active page, you must afterwards call $.mobile.resetActivePageHeight(); to ensure that the page height remains correct. An example illustrates this.

Fullscreen Toolbars

Fullscreen fixed toolbars sit on top of the content at all times when they are visible, and unlike regular fixed toolbars, fullscreen toolbars do not fall back to static positioning when toggled. Instead they disappear from the screen entirely. Fullscreen toolbars are ideal for more immersive interfaces, like a photo viewer that is meant to fill the entire screen with the photo itself and no distractions.

To enable this option on a fixed header or footer, add the data-fullscreen attribute to the element.

<div data-role="header" data-position="fixed" data-fullscreen="true">
  <h1>Fullscreen fixed header</h1>
</div>

Forms in toolbars

While all form elements are now tested to work correctly within static toolbars as of jQuery Mobile 1.1, we recommend extensive testing when using form elements within fixed toolbars or within any position: fixed elements. This can potentially trigger a number of unpredictable issues in various mobile browsers, Android 2.2/2.3 in particular (detailed in Known issues in Android 2.2/2.3, below).

Changes in jQuery Mobile 1.1

Prior to version 1.1, jQuery Mobile used dynamically re-positioned toolbars for the fixed header effect because very few mobile browsers supported the position:fixed CSS property, and simulating fixed support through the use of "fake" JavaScript overflow-scrolling behavior would have reduced our browser support reach, in addition to feeling unnatural on certain platforms. This behavior was not ideal, and jQuery Mobile 1.1 took a new approach to fixed toolbars that allows much broader support. The framework now offers true fixed toolbars on many popular platforms, while gracefully degrading non-supporting platforms to static positioning.

Polyfilling older platforms

The fixed toolbar plugin degrades gracefully on platforms that do not support CSS position:fixed properly, such as iOS4.3. If you still need to support fixed toolbars on that platform (with the show/hide behavior) included in previous releases, Filament Group has developed a polyfill that you can use.

• Github code repository with CSS, and JavaScript required for the fixed toolbars polyfill
• Preview URL using the code in the repo above

Just include the CSS and JS files after your references to jQuery Mobile and Fixed toolbars will work similarly to jQuery Mobile 1.0 on iOS4.3, with the inclusion of the new API for the 1.1 fixedtoolbar plugin.

If you have any improvements to suggest, fork the gist on github and let us know!

Known issue with form controls inside fixed toolbars, and programmatic scroll

An obscure issue exists in iOS5 and some Android platforms where form controls placed inside fixed-positioned containers can lose their hit area when the window is programatically scrolled (using window.scrollTo for example). This is not an issue specific to jQuery Mobile, but because of it, we recommend not programatically scrolling a document when using form controls inside jQuery Mobile fixed toolbars. This ticket from the Device Bugs project tracker explains this problem in more detail.

Known issues in Android 2.2/2.3

Android 2.2/2.3's implementation of position: fixed; can, in conjunction with seemingly unrelated styles and markup patterns, cause a number of strange issues, particularly in the case of position: absolute elements inside of position: fixed elements. While we've done our best to work around a number of these unique bugs within the scope of the library, custom styles may cause a number of issues.

• Form elements elsewhere on the page - select menus in particular - can fail to respond to user interaction when an empty absolute positioned element is placed within a fixed position element. In rare casesâand specific to Android 2.2âthis can cause entire pages to fail to respond to user interaction. This can seemingly be solved by adding any character to the absolute positioned element, including a non-breaking space, and in some cases even whitespace.
• The above-described issue can also be triggered by an absolute positioned image inside of a fixed position element, but only when that image is using something other than its inherent dimensions. If a height or width is specified on the image using CSS, or the image src is invalid (thus having no inherent height and width), this issue can occur. If an image that is inherently, say, 50x50 pixels is placed in a fixed element and left at its inherent dimensions, this issue does not seem to occur.
• When a position: fixed element appears anywhere on a page, most 2D CSS transforms will fail. Oddly, only translate transforms seem unaffected by this. Even more oddly, this issue is solved by setting a CSS opacity of .9 or below on the parent of the fixed element.
• Combinations of position: fixed and overflow properties are best avoided, as both have been known to cause unpredictable issues in older versions of Android OS.
• Any element that triggers the on-screen keyboard, when placed inside a position: fixed element, will fail to respond to user input when using anything other than the default keyboard. This includes Swype, XT9 or, it seems, any input method apart from the standard non-predictive keyboard.

While we will continue to try to find ways to mitigate these bugs as best we can, we currently advise against implementing fixed toolbars containing complicated user styles and form elements without extensive testing in all versions of Android's native browser.

Code examples:

Initialize the toolbar with the addBackBtn option specified:

$( ".selector" ).toolbar({
  addBackBtn: true
});

Get or set the addBackBtn option, after initialization:

// Getter
var addBackBtn = $( ".selector" ).toolbar( "option", "addBackBtn" );
 
// Setter
$( ".selector" ).toolbar( "option", "addBackBtn", true );

Code examples:

Initialize the toolbar with the backBtnText option specified:

$( ".selector" ).toolbar({
  backBtnText: "Previous"
});

Get or set the backBtnText option, after initialization:

// Getter
var backBtnText = $( ".selector" ).toolbar( "option", "backBtnText" );
 
// Setter
$( ".selector" ).toolbar( "option", "backBtnText", "Previous" );

Code examples:

Initialize the toolbar with the backBtnTheme option specified:

$( ".selector" ).toolbar({
  backBtnTheme: "b"
});

Get or set the backBtnTheme option, after initialization:

// Getter
var backBtnTheme = $( ".selector" ).toolbar( "option", "backBtnTheme" );
 
// Setter
$( ".selector" ).toolbar( "option", "backBtnTheme", "b" );

Code examples:

Initialize the toolbar with the defaults option specified:

$( ".selector" ).toolbar({
  defaults: true
});

Get or set the defaults option, after initialization:

// Getter
var defaults = $( ".selector" ).toolbar( "option", "defaults" );
 
// Setter
$( ".selector" ).toolbar( "option", "defaults", true );

Code examples:

Initialize the toolbar with the disablePageZoom option specified:

$( ".selector" ).toolbar({
  disablePageZoom: false
});

Get or set the disablePageZoom option, after initialization:

// Getter
var disablePageZoom = $( ".selector" ).toolbar( "option", "disablePageZoom" );
 
// Setter
$( ".selector" ).toolbar( "option", "disablePageZoom", false );

Code examples:

Initialize the toolbar with the disabled option specified:

$( ".selector" ).toolbar({
  disabled: true
});

Get or set the disabled option, after initialization:

// Getter
var disabled = $( ".selector" ).toolbar( "option", "disabled" );
 
// Setter
$( ".selector" ).toolbar( "option", "disabled", true );

Code examples:

Initialize the toolbar with the fullscreen option specified:

$( ".selector" ).toolbar({
  fullscreen: true
});

Get or set the fullscreen option, after initialization:

// Getter
var fullscreen = $( ".selector" ).toolbar( "option", "fullscreen" );
 
// Setter
$( ".selector" ).toolbar( "option", "fullscreen", true );

Code examples:

Initialize the toolbar with the hideDuringFocus option specified:

$( ".selector" ).toolbar({
  hideDuringFocus: "button"
});

Get or set the hideDuringFocus option, after initialization:

// Getter
var hideDuringFocus = $( ".selector" ).toolbar( "option", "hideDuringFocus" );
 
// Setter
$( ".selector" ).toolbar( "option", "hideDuringFocus", "button" );

Code examples:

Initialize the toolbar with the position option specified:

$( ".selector" ).toolbar({
  position: "fixed"
});

Get or set the position option, after initialization:

// Getter
var position = $( ".selector" ).toolbar( "option", "position" );
 
// Setter
$( ".selector" ).toolbar( "option", "position", "fixed" );

Code examples:

Initialize the toolbar with the tapToggle option specified:

$( ".selector" ).toolbar({
  tapToggle: false
});

Get or set the tapToggle option, after initialization:

// Getter
var tapToggle = $( ".selector" ).toolbar( "option", "tapToggle" );
 
// Setter
$( ".selector" ).toolbar( "option", "tapToggle", false );

Code examples:

Initialize the toolbar with the tapToggleBlacklist option specified:

$( ".selector" ).toolbar({
  tapToggleBlacklist: ".do-not-toggle-fixed-toolbar"
});

Get or set the tapToggleBlacklist option, after initialization:

// Getter
var tapToggleBlacklist = $( ".selector" ).toolbar( "option", "tapToggleBlacklist" );
 
// Setter
$( ".selector" ).toolbar( "option", "tapToggleBlacklist", ".do-not-toggle-fixed-toolbar" );

Code examples:

Initialize the toolbar with the theme option specified:

$( ".selector" ).toolbar({
  theme: "b"
});

Get or set the theme option, after initialization:

// Getter
var theme = $( ".selector" ).toolbar( "option", "theme" );
 
// Setter
$( ".selector" ).toolbar( "option", "theme", "b" );

Code examples:

Initialize the toolbar with the trackPersistentToolbars option specified:

$( ".selector" ).toolbar({
  trackPersistentToolbars: false
});

Get or set the trackPersistentToolbars option, after initialization:

// Getter
var trackPersistentToolbars = $( ".selector" ).toolbar( "option", "trackPersistentToolbars" );
 
// Setter
$( ".selector" ).toolbar( "option", "trackPersistentToolbars", false );

Code examples:

Initialize the toolbar with the transition option specified:

$( ".selector" ).toolbar({
  transition: "fade"
});

Get or set the transition option, after initialization:

// Getter
var transition = $( ".selector" ).toolbar( "option", "transition" );
 
// Setter
$( ".selector" ).toolbar( "option", "transition", "fade" );

Code examples:

Initialize the toolbar with the updatePagePadding option specified:

$( ".selector" ).toolbar({
  updatePagePadding: false
});

Get or set the updatePagePadding option, after initialization:

// Getter
var updatePagePadding = $( ".selector" ).toolbar( "option", "updatePagePadding" );
 
// Setter
$( ".selector" ).toolbar( "option", "updatePagePadding", false );

Code examples:

Initialize the toolbar with the visibleOnPageShow option specified:

$( ".selector" ).toolbar({
  visibleOnPageShow: false
});

Get or set the visibleOnPageShow option, after initialization:

// Getter
var visibleOnPageShow = $( ".selector" ).toolbar( "option", "visibleOnPageShow" );
 
// Setter
$( ".selector" ).toolbar( "option", "visibleOnPageShow", false );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "destroy" );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "disable" );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "enable" );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "hide" );

• optionName
  Type: String
  The name of the option to get.

var isDisabled = $( ".selector" ).toolbar( "option", "disabled" );

• This signature does not accept any arguments.

var options = $( ".selector" ).toolbar( "option" );

• optionName
  Type: String
  The name of the option to set.
• value
  Type: Object
  A value to set for the option.

$( ".selector" ).toolbar( "option", "disabled", true );

• options
  Type: Object
  A map of option-value pairs to set.

$( ".selector" ).toolbar( "option", { disabled: true } );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "refresh" );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "show" );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "toggle" );

• This method does not accept any arguments.

$( ".selector" ).toolbar( "updatePagePadding" );

• event
  Type: Event
• ui
  Type: Object

Note: The ui object is empty but included for consistency with other events.

$( ".selector" ).toolbar({
  create: function( event, ui ) {}
});

$( ".selector" ).on( "toolbarcreate", function( event, ui ) {} );

A basic example of a header

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>toolbar demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page1">
    <div data-role="header">
    <h1>Page Title</h1>
  </div>
  <div role="main" class="ui-content">
    <p>Some content here</p>
  </div>
</div>
 
</body>
</html>

A basic example of a page with fixed toolbars.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>toolbar demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page2">
  <div data-role="header" data-position="fixed" data-theme="b">
    <h1>Fixed Header</h1>
  </div>
  <div role="main" class="ui-content">
 
    <p>This page demonstrates the "fixed" toolbar mode. </p>
    <br /><br />
    <p>To enable this toolbar feature type, you apply the <code>data-position="fixed"</code> attribute to both the header and footer <code>div</code> elements.</p>
    <br /><br />
    <p>And we're adding more text here so that you can really see the fixed toobars in action.</p>
    <br /><br />
    <p>If you tap the screen while in the middle of the page (i.e. neither at the top nor the bottom of the page, the visibility of the toolbars will toggle</p>
    <p></p>
 
  </div>
    <div data-role="footer" data-theme="b" data-position="fixed">
    <h1>Fixed Footer</h1>
  </div>
</div>
 
</body>
</html>

Injecting a fixed toolbar

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>toolbar demo</title>
  <link rel="stylesheet" href="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.css">
  <script src="//code.jquery.com/jquery-1.10.2.min.js"></script>
  <script src="//code.jquery.com/mobile/1.4.5/jquery.mobile-1.4.5.min.js"></script>
</head>
<body>
 
<div data-role="page" id="page3">
  <div role="main" class="ui-content">
    <p>This page demonstrates how to correctly inject fixed toolbars.</p>
    <a href="#" id="inject-toolbar" class="ui-btn ui-corner-all ui-shadow ui-btn-inline">Inject Header</a>
  </div>
</div>
 
<script>
$.mobile.document.on( "click", "#inject-toolbar", function() {
  $( "<div data-role='header'><h1>Dynamic Fixed Toolbar Header</h1></div>")
    .appendTo( $( "#inject-toolbar" ).closest( ".ui-page" ) )
    .toolbar({ position: "fixed" });
 
  // This second step ensures that the insertion of the new toolbar does not
  // affect page height
  $.mobile.resetActivePageHeight();
});
</script>
 
</body>
</html>