Important: this documentation is not applicable to your currently selected format ads!
amp-sidebar
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-1.0.js"></script>
<script async custom-element="amp-sidebar" src="https://cdn.ampproject.org/v0/amp-sidebar-1.0.js"></script> <link rel="stylesheet" href="https://cdn.ampproject.org/v0/amp-sidebar-1.0.css">
Supported Layouts
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 ofamp-sidebar
with a setz-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>
Standalone use outside valid AMP documents
Bento allows you to use AMP components in non-AMP pages without needing to commit to fully valid AMP. You can take these components and place them in implementations with frameworks and CMSs that don't support AMP. Read more in our guide Use AMP components in non-AMP pages.
To find the standalone version of amp-sidebar
, see bento-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
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 andtoolbar-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">
.
- For instance, this would be a valid use of toolbar:
- 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.
- The
- Toolbar behavior is only applied while the
toolbar
attribute media-query is valid. Also, an element with thetoolbar-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. 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:
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>
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.
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.
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 theamp-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 theamp-sidebar
tag when the side bar is open on the page.
Validation
See amp-sidebar rules in the AMP validator specification.
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