Toolbar
API DocumentationThe toolbar widget is used to enhance headers and footers.
Markup
Header
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.
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. The framework add class ui-title
to headings that are immediate children of toolbars. All heading levels with class ui-title
are styled identically by default to maintain visual consistency.
Page Title
Footer
The footer is a toolbar at the bottom of the page that can contain a wide range of content, from form elements to navbars.
The footer bar has the same basic structure as the header except it uses the data-role
attribute value of footer
. Headings that are immediate children of the footer get class ui-title
, just like headers.
Powered by jQuery Mobile
Theme
The header and footer toolbar inherit the theme swatch from the page by default but you can easily set the theme swatch color. If you use external fixed toolbars you always have to set a theme, because there is no parent page from which they can inherit the theme.
Page Title
External toolbars
If you want to use the same toolbar on multiple pages, you can use external toolbars.
Fixed position
Toolbars can be set to fixed position by adding the data-position="fixed"
to the header or footer. This will make them remain at the top (header) or bottom (footer) of the window at all time instead of scrolling with the page. See fixed toolbars.
Fullscreen position
The toolbars can be set to fullscreen fixed position that overlays the toolbar over the content by adding the data-fullscreen="true"
to a fixed header. See fullscreen toolbars.
External fixed toolbars
Persistent toolbars
See persistent toolbars.
Buttons in toolbars
Header button position classes
You can use the ui-toolbar-header-button-left
and ui-toolbar-header-button-right
classes to position buttons in the header.
My App
Page Title
OptionsButtons in headers without a 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-toolbar-title"
so that the bar can get the height and display correctly.
Buttons in footers
The classes ui-toolbar-header-button-left
and ui-toolbar-header-button-right
were not meant to be used in footers, because they do not account for the possible presence of text, navbars, and and other elements often present in footers. You can nevertheless achieve a similar effect when you add a bit of custom CSS.
Adding back button to header
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 page plugin's addBackBtn
option is true. This can also be set via markup if the header has a data-add-back-button="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-button-text="previous"
attribute on your header 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 theme, you can use:
$.mobile.toolbar.prototype.options.backBtnTheme = "a";
If you're doing this programmatically, set this option inside the mobileinit
event handler.
Navbars
See navbar for examples of navigation bars inside toolbars.
Grouped buttons
To group buttons into a button set, wrap the links in an element with data-role="controlgroup"
and data-type="horizontal"
attributes.
My header
Adding padding
By default, toolbars don't have any padding to accommodate nav bars and other widgets. To add padding inside of a full-width toolbar, wrap the toolbar's contents in an element and add class ui-bar
to that element or apply your own padding rule in your custom CSS.