Table of contents

Usage
- Opening and closing the sidebar
- Toolbar
  - Behavior
Styling Toolbar
Attributes
Styling
Validation

Important: this documentation is not applicable to your currently selected format ads!

amp-sidebar

You can now use this component outside valid AMP documents using the Bento version of this component. Learn more in the Bento guide.

Description

Provides a way to display meta content intended for temporary access such as navigation, links, buttons, menus.

Required Scripts

<script async custom-element="amp-sidebar" src="https://cdn.ampproject.org/v0/amp-sidebar-0.1.js"></script>

Supported Layouts

nodisplay

Usage

Provides a way to display meta content intended for temporary access such as navigation, links, buttons, menus. The sidebar can be revealed by a button tap while the main content remains visually underneath.

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

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 using CSS (minimum width is 45px).
Touch zoom is disabled on the amp-sidebar and its mask when the sidebar is open.
<amp-sidebar> is recommended to be be a direct child of the <body> to preserve a logical DOM order (for accessibility) as well as to avoid altering its behavior by a container element. Note that having an ancestor of amp-sidebar with a set z-index may cause the sidebar to appear below other elements (such as headers), breaking its functionality.

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>

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>

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> or <ol> 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

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

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. Additionally, one can customize the opacity of the mask via amp-sidebar-mask.

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>

Auto scrolling within overflowing areas

amp-sidebar can automatically scroll the overflowing container to first element that is decorated with autoscroll as an attribute in both sidebar and toolbar cases.

This feature is useful when dealing with long navigation list and wanting the sidebar to scroll to the current navigation items when page loads.

When using toolbar feature, autoscroll only works if the <nav toolbar> element is set to overflow: auto or overflow: scroll.

<style amp-custom="">
  nav [toolbar] {
    overflow: auto;
  }
</style>

<amp-sidebar id="sidebar1" layout="nodisplay" side="right">
  <nav toolbar="(max-width: 767px)" toolbar-target="target-element">
    <ul>
      <li>Nav item 1</li>
      <li>Nav item 2</li>
      <li>Nav item 3</li>
      <li autoscroll class="currentPage">Nav item 4</li>
      <li>Nav item 5</li>
      <li>Nav item 6</li>
    </ul>
  </nav>
</amp-sidebar>

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

Please see this example file for a working example code.

Building Nested Menus

<amp-sidebar> supports drilldown (nested) menus through a child component named <amp-nested-menu>. With <amp-nested-menu>, <amp-sidebar> can support nesting one or more layers of submenus (and transition between them) as demonstrated by the following example:

When using amp-nested-menu, wrap every menu item in a li element to improve accessibility and keyboard support.

<button on="tap:sidebar1">Open Sidebar</button>
<amp-sidebar id="sidebar1" layout="nodisplay" style="width:300px">
  <amp-nested-menu layout="fill">
    <ul>
      <li>
        <h4 amp-nested-submenu-open>Open Sub-Menu</h4>
        <div amp-nested-submenu>
          <ul>
            <li>
              <h4 amp-nested-submenu-close>Go back</h4>
            </li>
            <li>
              <h4 amp-nested-submenu-open>Open Another Sub-Menu</h4>
              <div amp-nested-submenu>
                <h4 amp-nested-submenu-close>Go back</h4>
              </div>
            </li>
          </ul>
        </div>
      </li>
      <li>
        <a href="https://amp.dev/">Link</a>
      </li>
    </ul>
  </amp-nested-menu>
</amp-sidebar>

Open this snippet in playground

See <amp-nested-menu> for the full documentation on nested menus along with advanced feature such as dynamic content loading.

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.

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.

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.

data-disable-swipe-close

Including this attribute on amp-sidebar disables swipe to close. When using a mobile device or other touch enabled device, swiping to close the sidebar will be disabled.

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.

Visit AMP Start for responsive, pre-styled navigation menus that you can use in your AMP pages.

Validation

See amp-sidebar rules in the AMP validator specification.

Need more help?

You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.

Go to Stack Overflow

Found a bug or missing a feature?

The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.

Go to GitHub

amp-sidebar 1.0 0.2 0.1