Toolbar Widget


Toolbar Widgetversion added: 1.4

Description: Adds toolbars to the top and/or bottom of the page.

QuickNavExamples

Events

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.

1
2
3
<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

Note: The behavior whereby anchor elements are automatically enhanced as buttons is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must add button classes if you wish to style them as 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

Note: The behavior whereby the first two buttons automatically get the ui-btn-left and ui-btn-right classes is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must add those classes in your markup if you wish to position the buttons left and/or right.

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.

1
2
3
4
5
<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.

1
2
3
4
5
<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.

1
2
3
4
<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.

1
2
3
4
<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

Note: The options addBackBtn, backBtnTheme, and backBtnText have moved from the page widget to the toolbar widget as of jQuery Mobile 1.4.0.

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.)

1
2
3
<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

The footer bar is usually the last element inside each mobile page, and tends to be more freeform than the header in terms of content and functionality, but typically contains a combination of text and buttons.

Footer bar structure

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

1
2
3
<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

Note: The behavior whereby anchor elements are automatically enhanced as buttons is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Thereafter you must set the attribute data-role="button" on those anchors you wish the framework to enhance as 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.

1
2
3
4
5
<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.

1
<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:

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

Fixed footer markup example:

1
2
3
<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.

1
2
3
<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.

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.

No longer supported: touchOverflowEnabled

Prior to jQuery Mobile 1.1, true fixed toolbar support was contingent on native browser support for the CSS property overflow-scrolling: touch, which is currently only supported in iOS5. As of version 1.1, jQuery Mobile no longer uses this CSS property at all. We've removed all internal usage of this property in the framework, but we've left it defined globally on the $.mobile object to reduce the risk that its removal will cause trouble with existing applications. This property is flagged for removal, so please update your code to no longer use it. The support test for this property, however, remains defined under $.support and we have no plans to remove that test at this time.

Options

addBackBtn 

Type: Boolean
Default: false
Whether to automatically add a button to the header that will take the user to the previous page.

This option only affects header toolbar widgets.

This option is also exposed as a data attribute: data-add-back-btn="true".

Code examples:

Initialize the toolbar with the addBackBtn option specified:

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

Get or set the addBackBtn option, after initialization:

1
2
3
4
5
// Getter
var addBackBtn = $( ".selector" ).toolbar( "option", "addBackBtn" );
// Setter
$( ".selector" ).toolbar( "option", "addBackBtn", true );

backBtnText 

Type: String
Default: "Back"
The text to be shown on the back button.

This option only affects header toolbar widgets.

This option is also exposed as a data attribute: data-back-btn-text="Previous".

Code examples:

Initialize the toolbar with the backBtnText option specified:

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

Get or set the backBtnText option, after initialization:

1
2
3
4
5
// Getter
var backBtnText = $( ".selector" ).toolbar( "option", "backBtnText" );
// Setter
$( ".selector" ).toolbar( "option", "backBtnText", "Previous" );

backBtnTheme 

Type: String
Default: null, inherited from parent
Sets the color theme swatch for the back button. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option is also exposed as a data attribute: data-back-btn-theme="b".

Code examples:

Initialize the toolbar with the backBtnTheme option specified:

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

Get or set the backBtnTheme option, after initialization:

1
2
3
4
5
// Getter
var backBtnTheme = $( ".selector" ).toolbar( "option", "backBtnTheme" );
// Setter
$( ".selector" ).toolbar( "option", "backBtnTheme", "b" );

defaults 

Type: Boolean
Default: false
Seting this option to true indicates that other widgets options have default values and causes jQuery Mobile's widget autoenhancement code to omit the step where it retrieves option values from data attributes. This can improve startup time.

This option is also exposed as a data attribute: data-defaults="true".

Code examples:

Initialize the toolbar with the defaults option specified:

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

Get or set the defaults option, after initialization:

1
2
3
4
5
// Getter
var defaults = $( ".selector" ).toolbar( "option", "defaults" );
// Setter
$( ".selector" ).toolbar( "option", "defaults", true );

disablePageZoom 

Type: Boolean
Default: true
This option is provided by the fixedToolbar extension.

Sets whether to disable page zoom whenever the page containing the fixed toolbar is shown.

This option is also exposed as a data attribute: data-disable-page-zoom="false".

Code examples:

Initialize the toolbar with the disablePageZoom option specified:

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

Get or set the disablePageZoom option, after initialization:

1
2
3
4
5
// Getter
var disablePageZoom = $( ".selector" ).toolbar( "option", "disablePageZoom" );
// Setter
$( ".selector" ).toolbar( "option", "disablePageZoom", false );

disabled 

Type: Boolean
Default: false
Disables the toolbar if set to true.

This option is also exposed as a data attribute: data-disabled="true".

Code examples:

Initialize the toolbar with the disabled option specified:

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

Get or set the disabled option, after initialization:

1
2
3
4
5
// Getter
var disabled = $( ".selector" ).toolbar( "option", "disabled" );
// Setter
$( ".selector" ).toolbar( "option", "disabled", true );

fullscreen 

Type: Boolean
Default: false
This option is provided by the fixedToolbar extension.

Sets whether the toolbar should be hidden entirely when the page is tapped.

This option is also exposed as a data attribute: data-fullscreen="true".

Code examples:

Initialize the toolbar with the fullscreen option specified:

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

Get or set the fullscreen option, after initialization:

1
2
3
4
5
// Getter
var fullscreen = $( ".selector" ).toolbar( "option", "fullscreen" );
// Setter
$( ".selector" ).toolbar( "option", "fullscreen", true );

hideDuringFocus 

Type: String
Default: "input, textarea, select"
This option is provided by the fixedToolbar extension.

The value of this option is a CSS selector for those elements that, when focused, should cause the fixed toolbar to be hidden and conversely, to be shown upon loss of focus.

This option is also exposed as a data attribute: data-hide-during-focus="button".

Code examples:

Initialize the toolbar with the hideDuringFocus option specified:

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

Get or set the hideDuringFocus option, after initialization:

1
2
3
4
5
// Getter
var hideDuringFocus = $( ".selector" ).toolbar( "option", "hideDuringFocus" );
// Setter
$( ".selector" ).toolbar( "option", "hideDuringFocus", "button" );

position 

Type: String
Default: null
This option is provided by the fixedToolbar extension.

Causes the toolbar to float above the content via CSS position: fixed when set to "fixed".

This option is also exposed as a data attribute: data-position="fixed".

Code examples:

Initialize the toolbar with the position option specified:

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

Get or set the position option, after initialization:

1
2
3
4
5
// Getter
var position = $( ".selector" ).toolbar( "option", "position" );
// Setter
$( ".selector" ).toolbar( "option", "position", "fixed" );

supportBlacklist 

Type: Function()
Default: default blacklist
This option is provided by the fixedToolbar extension.

The value of this option is a function that will return true on platforms where toolbar widgets should not be displayed as fixed.

The default value of this option is a function that returns true whenever the value of $.support.fixedPosition is false.

tapToggle 

Type: Boolean
Default: true
This option is provided by the fixedToolbar extension.

Sets whether the fixed toolbar's visibility can be toggled by tapping on the page.

This option is also exposed as a data attribute: data-tap-toggle="false".

Code examples:

Initialize the toolbar with the tapToggle option specified:

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

Get or set the tapToggle option, after initialization:

1
2
3
4
5
// Getter
var tapToggle = $( ".selector" ).toolbar( "option", "tapToggle" );
// Setter
$( ".selector" ).toolbar( "option", "tapToggle", false );

tapToggleBlacklist 

Type: String
Default: "a, button, input, select, textarea, .ui-header-fixed, .ui-footer-fixed, .ui-flipswitch, .ui-popup, .ui-panel, .ui-panel-dismiss-open"
This option is provided by the fixedToolbar extension.

When the user taps on the page and the tapToggle option is set on the fixed toolbar widget, the element on which the user has tapped is examined before the visibility of the toolbar is toggled. If the element on which the user has tapped matches the selector provided as the value of this option, then the toolbar is not toggled.

This option is also exposed as a data attribute: data-tap-toggle-blacklist=".do-not-toggle-fixed-toolbar".

Code examples:

Initialize the toolbar with the tapToggleBlacklist option specified:

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

Get or set the tapToggleBlacklist option, after initialization:

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

theme 

Type: String
Default: null, inherited from parent
Sets the color scheme (swatch) for the toolbar widget. It accepts a single letter from a-z that maps to the swatches included in your theme.

Possible values: swatch letter (a-z).

This option is also exposed as a data attribute: data-theme="b".

Code examples:

Initialize the toolbar with the theme option specified:

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

Get or set the theme option, after initialization:

1
2
3
4
5
// Getter
var theme = $( ".selector" ).toolbar( "option", "theme" );
// Setter
$( ".selector" ).toolbar( "option", "theme", "b" );

trackPersistentToolbars 

Type: Boolean
Default: true
This option is provided by the fixedToolbar extension.

Whether to persist the toolbar across pages.

This option is also exposed as a data attribute: data-track-persistent-toolbars="false".

(version deprecated: 1.4.0)
Code examples:

Initialize the toolbar with the trackPersistentToolbars option specified:

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

Get or set the trackPersistentToolbars option, after initialization:

1
2
3
4
5
// Getter
var trackPersistentToolbars = $( ".selector" ).toolbar( "option", "trackPersistentToolbars" );
// Setter
$( ".selector" ).toolbar( "option", "trackPersistentToolbars", false );

transition 

Type: String
Default: "slide"
This option is provided by the fixedToolbar extension.

The transition to apply when showing/hiding the fixed toolbar.

The following values are recognized:

"none" The fixed toolbar appears and disappears abruptly, without any transition.
"slide" The fixed slides in and out when it is toggled. "slideup" is used for headers, and "slidedown" is used for footers.
"fade" The fixed fades in and out when it is toggled.
Code examples:

Initialize the toolbar with the transition option specified:

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

Get or set the transition option, after initialization:

1
2
3
4
5
// Getter
var transition = $( ".selector" ).toolbar( "option", "transition" );
// Setter
$( ".selector" ).toolbar( "option", "transition", "fade" );

updatePagePadding 

Type: Boolean
Default: true
This option is provided by the fixedToolbar extension.

Whether to set the page content div's top and bottom padding to the height of the toolbar.

This option is also exposed as a data attribute: data-update-page-padding="false".

Code examples:

Initialize the toolbar with the updatePagePadding option specified:

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

Get or set the updatePagePadding option, after initialization:

1
2
3
4
5
// Getter
var updatePagePadding = $( ".selector" ).toolbar( "option", "updatePagePadding" );
// Setter
$( ".selector" ).toolbar( "option", "updatePagePadding", false );

visibleOnPageShow 

Type: Boolean
Default: true
This option is provided by the fixedToolbar extension.

Whether the toolbar is shown along with the page.

This option is also exposed as a data attribute: data-visible-on-page-show="false".

Code examples:

Initialize the toolbar with the visibleOnPageShow option specified:

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

Get or set the visibleOnPageShow option, after initialization:

1
2
3
4
5
// Getter
var visibleOnPageShow = $( ".selector" ).toolbar( "option", "visibleOnPageShow" );
// Setter
$( ".selector" ).toolbar( "option", "visibleOnPageShow", false );

Methods

destroy()Returns: jQuery (plugin only)

Removes the toolbar functionality completely. This will return the element back to its pre-init state.
  • This method does not accept any arguments.
Code examples:

Invoke the destroy method:

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

disable()Returns: jQuery (plugin only)

Disables the toolbar.
  • This method does not accept any arguments.
Code examples:

Invoke the disable method:

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

enable()Returns: jQuery (plugin only)

Enables the toolbar.
  • This method does not accept any arguments.
Code examples:

Invoke the enable method:

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

hide()Returns: jQuery (plugin only)

This method is provided by the fixedToolbar extension.

Hides the toolbar.

  • This method does not accept any arguments.
Code examples:

Invoke the hide method:

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

option( optionName )Returns: Object

Gets the value currently associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to get.
Code examples:

Invoke the method:

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

option()Returns: PlainObject

Gets an object containing key/value pairs representing the current toolbar options hash.
  • This signature does not accept any arguments.
Code examples:

Invoke the method:

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

option( optionName, value )Returns: jQuery (plugin only)

Sets the value of the toolbar option associated with the specified optionName.
  • optionName
    Type: String
    The name of the option to set.
  • value
    Type: Object
    A value to set for the option.
Code examples:

Invoke the method:

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

option( options )Returns: jQuery (plugin only)

Sets one or more options for the toolbar.
  • options
    Type: Object
    A map of option-value pairs to set.
Code examples:

Invoke the method:

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

refresh()Returns: jQuery (plugin only)

Update the toolbar.

If you manipulate a toolbar via JavaScript, you must call the refresh method on it to update the visual styling.

  • This method does not accept any arguments.
Code examples:

Invoke the refresh method:

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

show()Returns: jQuery (plugin only)

This method is provided by the fixedToolbar extension.

Shows the toolbar.

  • This method does not accept any arguments.
Code examples:

Invoke the show method:

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

toggle()Returns: jQuery (plugin only)

This method is provided by the fixedToolbar extension.

Calls either the show or the hide method, depending on whether the toolbar is visible.

  • This method does not accept any arguments.
Code examples:

Invoke the toggle method:

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

updatePagePadding()Returns: jQuery (plugin only)

Sets the top and bottom padding for the content element of the page to the height of the toolbar.
  • This method does not accept any arguments.
Code examples:

Invoke the updatePagePadding method:

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

Events

create( event, ui )Type: toolbarcreate

Triggered when the toolbar is created.

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

Code examples:

Initialize the toolbar with the create callback specified:

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

Bind an event listener to the toolbarcreate event:

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

Examples:

A basic example of a header

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
<!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>

Demo:

A basic example of a page with fixed toolbars.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
<!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>

Demo:

Injecting a fixed toolbar

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
<!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>

Demo: