To close, click off the panel, swipe left or right, hit the Esc key, or use the button below:

This panel has all the default options: positioned on the left with the reveal display mode. The panel markup is before the header, content and footer in the source order.

Left panel examples

Right panel examples

Where panel markup goes in a page

Panels are designed to be as flexible as possible to make it easy to create menus, collapsible columns, drawers, inspectors panes and more.

A panel must be a sibling to the header, content and footer elements inside a jQuery Mobile page. You can add the panel markup either before or after these elements, but not in between. A panel cannot be placed outside a page, but this constraint will be removed in a future version.

Here is an example of the panel before the header, content and footer in the source order:

<div data-role="page"> <div data-role="panel" id="mypanel"> <!-- panel content goes here --> </div><!-- /panel --> <!-- header --> <!-- content --> <!-- footer --> </div><!-- page -->

Alternately, it's possible to add the panel markup after the header, content and footer in the source order, just before the end of the page container. Where in the source order you place the panel markup will depend on how you want to page content to read for people experiencing the page in a C-grade device (HTML only) or for a screen reader.

Panel markup conventions

A panel consists of a container with a data-role="panel" attribute and a unique ID . This ID will be referenced by the link or button to open and close the panel. The most basic panel markup looks like this:

<div data-role="panel" id="mypanel"> <!-- panel content goes here --> </div>

The position of the panel on the screen is set by the data-position attribute. The defaults to left , meaning it will appear from the left edge of the screen. Specify data-position="right" for it to appear from the right edge instead.

The display mode of the panel is set by the data-display attribute. The defaults to reveal , meaning the panel will sit under the page and reveal as the page slides away. Specify data-display="overlay" for the panel to appear on top of the page contents. A third mode, data-display="push" animates both the panel and page at the same time.

Here is an example of a panel with a custom position and display option set:

<div data-role="panel" id="mypanel" data-position="right" data-display="push"> <!-- panel content goes here --> </div>

Opening a panel

A panel's visibility is toggled by a link somewhere on the page or by calling the panel's open method directly. The defaults place the panel on the left and it will be revealed. Open a panel programmatically like this:

$( "#idofpanel" ).panel( "open" , optionsHash );

To control a panel from a link, point the href to references the ID of the panel you want to toggle ( mypanel in the example above). This instructs the framework to bind the link to the panel. This link will toggle the visibility of the panel so tapping it will open the panel, and tapping it again will close it.

<a href="#mypanel">Open panel</a>

When using markup to control panels, you can only have a single panel open at once. Clicking a link to open a panel while one is already open will auto-close the first. This is done to keep the markup-only configuration simple.

That said, it's possible to open multiple panels at once programmatically:

$( "#idofpanel" ) .panel( "open" , optionsHash ) .then( function( options ){ $( "#idofpanel2" ).panel( "open" , options ); });

Closing a panel

Clicking the link that opened the panel, swiping left or right, or tapping the Esc key will close the panel. To turn off the swipe to close behavior, add the data-swipe-close="false" attribute to the panel.

By default, panels can also be closed clicking outside the panel onto the page contents. To prevent this behavior, add the data-dismissible="false" attribute to the panel. It's possible to have the panel and page sit side-by-side at wider screen widths and prevent the click-out-to-close behavior only above a certain screen width by applying a media query. See the responsive section below for details.

A panel can also be closed by calling the panel's close method directly.

$( "#idofpanel" ).panel( "close" );

It's common to also add a close button inside the panel. To add the link that will close the panel, add the data-rel="close" attribute to tell the framework to close that panel when clicked. It's important to ensure that this link also makes sense if JavaScript isn't available, so we recommend that the href points to the ID of the page where the user should jump to when closing. For example, if the button to open the panel is in the header bar that has and ID of my-header , the close link in the panel should be:

<a href="#my-header" data-rel="close">Close panel</a>

Panel animations

Panels will animate if the browser supports 3D transforms, the same criteria for CSS animation support we use for page transitions. Panel animations use translate3d(x,y,z) CSS transforms to ensure they are hardware accelerated and smooth.

The framework has a feature test to detect if the required CSS properties are supported and will fall back to a simple hide/show if not available. After thorough testing, we decided to not animate panels on less capable platforms because the choppier animations weren't a better experience than a simple hide/show.

The animate option allows you to turn off panel animations for all devices. To turn off animations via markup, add the data-animate="false" attribute to the panel container.

Panel positioning

The panel will be displayed with the position:absolute CSS property, meaning it will scroll with the page. When a panel is a opened the framework checks to see if the bottom of the panel contents is in view and, if not, scrolls to the top of the page.

You can set a panel to position:fixed , so its contents will appear no matter how far down the page you're scrolled, by adding the data-position-fixed="true" attribute to the panel. The framework also checks to see if the panel contents will fit within the viewport before applying the fixed positioning because this property would prevent the panel contents from scrolling and using overflow is not well supported enough to use at this time. If the panel contents are too long to fit within the viewport, the framework will simply display the panel without absolute positioning.

In general, we recommend that you place the buttons that open the panel at the very top of the screen which is the most common UI pattern for panels. This will avoid the need to scroll and also makes the transitions a bit smoother.

Note that there are issues with fixed positioning within Android WebView applications (not the browser) that can cause layout issues, especially when hardware acceleration isn't enabled. We recommend not to use the fixed position panel option if deploying to an Android app. Also, although the framework supports the combination of panels and fixed toolbars, fixed toolbars don't transition together with the page content.

Styling panels

By default, panels have very simple styles to let you customize them as needed. Panels are essentially just simple blocks with no margins that sit on either side of the page content. The framework wraps the panel content in a div with class ui-pannel-inner which has a padding of 15 pixels. If needed you can override this with custom CSS or use option classes.panelInner to set a different class name for the div

Panels have a fixed width of 17em (272 pixels) which is narrow enough to still show some of the page contents when open to make clicking out to close easy, and still looks good on wider tablet or desktop screens. The styles to set widths on panels are fairly complex but these can be overridden with CSS as needed.

Other than the width and 100% height styles, panels have very little styling on their own. You can set a theme on the panel by add a data-theme to the panel container or add your own classes to style it as needed.

Note that adding padding, borders, or margins directly to the panel container will alter the overall dimensions and could cause the positioning and animation to be affected.

To add padding to a panel, we recommend adding a container inside the panel and applying styles to that to avoid any issues. All the examples on this page follow this pattern.

Making the panel responsive

When the push or reveal display is used, a panel pushes the page aside when it opens. Since some of the page is pushed offscreen, the panel is modal and must be closed to interact with the page content again. On larger screens, you may want to have the panel work more like a collapsible column that can be opened and used alongside the page to take better use of the screen real estate.

To make the page work alongside the open panel, it needs to re-flow to a narrower width so it will fit next to the panel. This can be done purely with CSS by adding a left or right margin equal to the panel width (17em) to the page contents to force a re-flow. Second, the invisible layer placed over the page for the click out to dismiss behavior is hidden with CSS so you can click on the page and not close the menu.

Here is an example of these rules wrapped in a media query to only apply this behavior above 35em (560px):

/* wrap push on wide viewports once open */ @media (min-width: 35em){ .ui-responsive-panel.ui-page-panel-open .ui-panel-content-fixed-toolbar-open.ui-panel-content-fixed-toolbar-display-push, .ui-responsive-panel.ui-page-panel-open .ui-panel-content-fixed-toolbar-open.ui-panel-content-fixed-toolbar-display-reveal, .ui-responsive-panel.ui-page-panel-open .ui-panel-content-wrap-open.ui-panel-content-wrap-display-push, .ui-responsive-panel.ui-page-panel-open .ui-panel-content-wrap-open.ui-panel-content-wrap-display-reveal { margin-right: 17em; } .ui-responsive-panel.ui-page-panel-open .ui-panel-content-fixed-toolbar-open.ui-panel-content-wrap-display-push.ui-panel-content-fixed-toolbar-position-right, .ui-responsive-panel.ui-page-panel-open .ui-panel-content-fixed-toolbar-open.ui-panel-content-wrap-display-reveal.ui-panel-content-fixed-toolbar-position-right, .ui-responsive-panel.ui-page-panel-open .ui-panel-content-wrap-open.ui-panel-content-wrap-display-push.ui-panel-content-wrap-position-right, .ui-responsive-panel.ui-page-panel-open .ui-panel-content-wrap-open.ui-panel-content-wrap-display-reveal.ui-panel-content-wrap-position-right { margin: 0 0 0 17em; } .ui-responsive-panel .ui-panel-dismiss-display-push { display: none; } }

Applying a preset breakpoint