amp-sidebar

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

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>

See live demos at AMP By Example.

Use of amp-sidebar is supported within the amp-story component.

Behavior

The <amp-sidebar> must be a direct child of <amp-story>.
The sidebar defaults to the "end" side, meaning right for left-right languages and left for right-to-left languages.
The <amp-sidebar> has default background color of white and is overridable in CSS.
Default width of <amp-sidebar> is 75% of the viewport up to 360px, on and 25% up to 600px for desktop experiences. Width can be overriden using the CSS width property, but has to be contained within these intervals.
A 'hamburger' style button that opens/closes the sidebar will appear on the story UI.

There are certain restrictions on what attributes and features are allowed in order to provide a consistent UI experience across the story platform. The following are allowed attributes and features of an amp-sidebar within an amp-story.

Example: Basic Sidebar in a Story

The following example shows a simple amp-sidebar within an amp-story.

...
<body>
    <amp-story standalone>
      <amp-sidebar id="sidebar1" layout="nodisplay">
        <ul>
          <li><a href="https://www.ampproject.org"> External Link </a></li>
          <li>Nav item 2</li>
          <li>Nav item 3</li>
        </ul>
      </amp-sidebar>
      <amp-story-page id="cover">
        <amp-story-grid-layer template="fill">
          <h1>Hello World</h1>
          <p>This is the cover page of this story.</p>
        </amp-story-grid-layer>
      </amp-story-page>
      ...
  </body>

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.

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.

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.

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.

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

Components

{{title}}

Results

{{title}}

;(

Something went wrong…

¯\_(ツ)_/¯

No results found.

Important Components

<{{title}}>

Popular Articles

{{title}}

amp-sidebar

Overview

Behavior

Opening and closing the sidebar

Behavior

Sidebar for Stories

Behavior

Allowed Attributes

Attributes

side

layout

open

data-close-button-aria-label

toolbar

common attributes

Styling

Auto scrolling within overflowing areas

UX considerations

Validation

Components

{{title}}

Results

{{title}}

;(

Something went wrong…

¯\_(ツ)_/¯

No results found.

Important Components

<{{title}}>

Popular Articles

{{title}}

amp-sidebar

Overview

Behavior

Opening and closing the sidebar

Toolbar

Behavior

Styling Toolbar

Sidebar for Stories

Behavior

Allowed Attributes

Attributes

side

layout

open

data-close-button-aria-label

toolbar

toolbar-target

common attributes

Styling

Auto scrolling within overflowing areas

UX considerations

Validation