Description A sidebar provides a way to display meta content intended for temporary access (navigation links, buttons, menus, etc.). The sidebar can be revealed by a button tap while the main content remains visually underneath.
Required Script <script async custom-element="amp-sidebar" src="https://cdn.ampproject.org/v0/amp-sidebar-0.1.js"></script>
Supported Layouts nodisplay
Examples See AMP By Example's amp-sidebar example.

Overview

<amp-sidebar> hides meta content intended for temporary access (navigation links, buttons, menus, etc.). <amp-sidebar> can be opened and closed by button taps, and tapping outside of amp-sidebar. However, optional attributes that accept media queries can be used to display meta content in other parts of the site. Child <nav toolbar="(media query)" toolbar-target="elementID"> elements allow for content within the sidebar to be displayed on other parts of the main content.

Behavior

  • The <amp-sidebar> should be a direct child of the <body>.
  • The sidebar can only appear on the left or right side of a page.
  • The <amp-sidebar> may contain any valid HTML elements (supported by AMP).
  • The <amp-sidebar> may contain any of the following AMP elements:
    • <amp-accordion>
    • <amp-img>
    • <amp-fit-text>
    • <amp-list>
    • <amp-live-list>
    • <amp-social-share>
  • The max-height of the sidebar is 100vh, if the height exceeds 100vh then a vertical scrollbar appears. The default height is set to 100vh in CSS and is overridable in CSS.
  • The width of the sidebar can be set and adjusted between 45px and 80vw using CSS.
  • Touch zoom is disabled on the amp-sidebar and it's mask when the sidebar is open.

Example:

In the following example, we use amp-sidebar to contain navigation items. However, The second and fourth item, Nav Item 2 and Nav Item 4, are assigned to element id that is on the page. By using the on attribute, we can scroll smoothly to the element, using the element id and scrollTo.

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <ul>
    <li>Nav item 1</li>
    <li><a href="#idTwo" on="tap:idTwo.scrollTo">Nav item 2</a></li>
    <li>Nav item 3</li>
    <li><a href="#idFour" on="tap:idFour.scrollTo">Nav item 4</a></li>
    <li>Nav item 5</li>
    <li>Nav item 6</li>
  </ul>
</amp-sidebar>

Opening and closing the sidebar

To toggle, open, or close the sidebar when an element is tapped or clicked, set the on action attribute on the element, and specify one of the following action methods:

Action Description
open (default) Opens the sidebar
close Closes the sidebar
toggle Toggles the sidebar state

If the user taps back on the partially-visible main content area, this closes the sidebar.

Alternatively, pressing the escape key on the keyboard will also close the sidebar.

Example:

<button class="hamburger" on='tap:sidebar1.toggle'></button>
<button on='tap:sidebar1'>Open</button>
<button on='tap:sidebar1.open'>Open</button>
<button on='tap:sidebar1.close'>x</button>

Toolbar (Experimental)

You can create a toolbar element that displays in the <body> by specifying the toolbar attribute with a media query and a toolbar-target attribute with an element id on a <nav> element that is a child of <amp-sidebar>. The toolbar duplicates the <nav> element and its children and appends the element into the toolbar-target element.

Behavior

  • The sidebar may implement toolbars by adding nav elements with the toolbar attribute and toolbar-target attribute.
  • The nav element must be a child of <amp-sidebar> and follow this format: <nav toolbar="(media-query)" toolbar-target="elementID">.
    • For instance, this would be a valid use of toolbar: <nav toolbar="(max-width: 1024px)" toolbar-target="target-element">.
  • The nav containing the toolbar attribute must only contain a single <ul> element, that contains <li> elements.
    • The <li> elements may contain any valid HTML elements (supported by AMP), or any of the AMP elements that <amp-sidebar> supports.
  • Toolbar behavior is only applied while the toolbar attribute media-query is valid. Also, an element with the toolbar-target attribute id must exist on the page for the toolbar to be applied.

Example: Basic Toolbar

In the following example, we display a toolbar if the window width is less than or equal to 767px. The toolbar contains a search input element. The toolbar element will be appended to the <div id="target-element"> element.

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <ul>
    <li>Nav item 1</li>
    <li><a href="#idTwo" on="tap:idTwo.scrollTo">Nav item 2</a></li>
    <li>Nav item 3</li>
    <li><a href="#idFour" on="tap:idFour.scrollTo">Nav item 4</a></li>
    <li>Nav item 5</li>
    <li>Nav item 6</li>
  </ul>

  <nav toolbar="(max-width: 767px)" toolbar-target="target-element">
    <ul>
      <li>
        <input placeholder="Search..."/>
      </li>
    </ul>
  </nav>
</amp-sidebar>

<div id="target-element">
</div>

Styling Toolbar

The toolbar element within the <amp-sidebar> element, will have classes applied to the element depending if the toolbar-target element is shown or hidden. This is useful for applying different styles on the toolbar element and then toolbar-target element. The classes are amp-sidebar-toolbar-target-shown, and amp-sidebar-toolbar-target-hidden. The class amp-sidebar-toolbar-target-shown is applied to the toolbar element when the toolbar-target element is shown. The class amp-sidebar-toolbar-target-hidden is applied to the toolbar element when the toolbar-target element is hidden.

Example: Toolbar State Classes

In the following example, we display a toolbar if the window width is less than or equal to 767px. The toolbar contains a search input element. The toolbar element will be appended to the <div id="target-element"> element. However, we added some custom styles to hide the toolbar element, when the <div id="toolbar-target"> element is shown.

<style amp-custom="">

  .amp-sidebar-toolbar-target-shown {
      display: none;
  }

</style>

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <ul>
    <li>Nav item 1</li>
    <li><a href="#idTwo" on="tap:idTwo.scrollTo">Nav item 2</a></li>
    <li>Nav item 3</li>
    <li><a href="#idFour" on="tap:idFour.scrollTo">Nav item 4</a></li>
    <li>Nav item 5</li>
    <li>Nav item 6</li>
  </ul>

  <nav toolbar="(max-width: 767px)" toolbar-target="target-element">
    <ul>
      <li>
        <input placeholder="Search..."/>
      </li>
    </ul>
  </nav>
</amp-sidebar>

<div id="target-element">
</div>

Attributes

side

Indicates what side of the page the sidebar should open from, either left or right. If a side is not specified, the side value will be inherited from the body tag's dir attribute (ltr => left , rtl => right); if no dir exists, the side defaults to left.

layout

Specifies the display layout of the sidebar, which must be nodisplay.

open

This attribute is present when the sidebar is open.

data-close-button-aria-label

Optional attribute used to set ARIA label for the close button added for accessibility.

toolbar

This attribute is present on child <nav toolbar="(media-query)" toolbar-target="elementID"> elements, and accepts a media query of when to show a toolbar. See the Toolbar section for more information on using toolbars.

toolbar-target

This attribute is present on child <nav toolbar="(media-query)" toolbar-target="elementID">, and accepts an id of an element on the page. The toolbar-target attribute will place the toolbar into the specified id of the element on the page, without the default toolbar styling. See the Toolbar section for more information on using toolbars.

common attributes

This element includes common attributes extended to AMP components.

Styling

The amp-sidebar component can be styled with standard CSS.

  • The width of the amp-sidebar may be set to adjust the width between the pre-set min(45px) and max(80vw) values.
  • The height of the amp-sidebar may be set to adjust the height of the sidebar, if required. If the height exceeds 100vw, the sidebar will have a vertical scrollbar. The preset height of the sidebar is 100vw and can be overridden in CSS to make it shorter.
  • The current state of the sidebar is exposed via the open attribute that is set on the amp-sidebar tag when the side bar is open on the page.

UX considerations

When using <amp-sidebar>, keep in mind that your users will often view your page on mobile in an AMP viewer, which may display a fixed-position header. In addition, browsers often display their own fixed header at the top of the page. Adding another fixed-position element at the top of the screen would take up a large amount of mobile screen space with content that gives the user no new information.

For this reason, we recommend that affordances to open the sidebar are not placed in a fixed, full-width header.

Validation

See amp-sidebar rules in the AMP validator specification.