@ampproject/amp-sidebar
Advanced tools
The Bento Sidebar 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.
Use Bento Sidebar as a web component <bento-sidebar>, or a Preact/React functional component <BentoSidebar>.
You must include each Bento component's required CSS library to guarantee proper loading and before adding custom styles. Or use the light-weight pre-upgrade styles available inline. See Layout and style.
The examples below demonstrate use of the <bento-sidebar> web component.
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-sidebar
import '@ampproject/bento-sidebar';
[/example]
<script>[example preview="top-frame" playground="false"]
<head>
<!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
<style data-bento-boilerplate>
bento-sidebar:not([open]) {
display: none !important;
}
</style>
<script async src="https://cdn.ampproject.org/v0/bento-sidebar-1.0.js"></script>
</head>
<body>
<bento-sidebar id="sidebar1" side="right">
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</li>
<li>Nav item 5</li>
<li>Nav item 6</li>
</ul>
</bento-sidebar>
<div class="buttons" style="margin-top: 8px;">
<button id="open-sidebar">
Open sidebar
</button>
</div>
<script>
(async () => {
const sidebar = document.querySelector('#sidebar1');
await customElements.whenDefined('bento-sidebar');
const api = await sidebar.getApi();
// set up button actions
document.querySelector('#open-sidebar').onclick = () => api.open();
})();
</script>
</body>
[/example]
You can create a Bento 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 <bento-sidebar>. The toolbar duplicates the <nav> element and its children and appends the element into the toolbar-target element.
toolbar attribute and toolbar-target attribute.<bento-sidebar> and follow this format: <nav toolbar="(media-query)" toolbar-target="elementID">.
<nav toolbar="(max-width: 1024px)" toolbar-target="target-element">.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.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.
<bento-sidebar id="sidebar1" side="right">
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</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>
</bento-sidebar>
<div id="target-element"></div>
Bento enabled components used as a standalone web component are highly interactive through their API. The bento-sidebar component API is accessible by including the following script tag in your document:
await customElements.whenDefined('bento-sidebar');
const api = await carousel.getApi();
The bento-sidebar API allows you to perform the following actions:
open() Opens the sidebar.
api.open();
close() Closes the sidebar.
api.close();
toggle() Toggles the sidebar open state.
api.toggle(0);
Each Bento component has a small CSS library you must include to guarantee proper loading without content shifts. Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.
<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-sidebar-1.0.css">
Alternatively, you may also make the light-weight pre-upgrade styles available inline:
<style data-bento-boilerplate>
bento-sidebar:not([open]) {
display: none !important;
}
</style>
The bento-sidebar component can be styled with standard CSS.
width of the bento-sidebar may be set to adjust the width from the pre-set 45px value.bento-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.open attribute that is set on the bento-sidebar tag when the side bar is open on the page.bento-sidebar[open] {
height: 100%;
width: 50px;
}
When using <bento-sidebar>, keep in mind that your users will often view your page on mobile, 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.
<bento-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 bento-sidebar with a set z-index may cause the sidebar to appear below other elements (such as headers), breaking its functionality.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.
This attribute is present when the sidebar is open.
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.
The examples below demonstrate use of the <BentoSidebar> as a functional component usable with the Preact or React libraries.
[example preview="top-frame" playground="false"]
Install via npm:
npm install @ampproject/bento-sidebar
import React from 'react';
import { BentoSidebar } from '@ampproject/bento-sidebar/react';
import '@ampproject/bento-sidebar/styles.css';
function App() {
return (
<BentoSidebar>
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</li>
<li>Nav item 5</li>
<li>Nav item 6</li>
</ul>
</BentoSidebar>
);
}
[/example]
You can create a Bento Toolbar element that displays in the <body> by specifying the toolbar prop with a media query and a toolbarTarget prop with an element id on a <BentoSidebarToolbar> component that is a child of <BentoSidebar>. The toolbar duplicates the <BentoSidebarToolbar> element and its children and appends the element into the toolbarTarget element.
toolbar prop and toolbarTarget prop.<BentoSidebar> and follow this format: <BentoSidebarToolbar toolbar="(media-query)" toolbarTarget="elementID">.
<BentoSidebarToolbar toolbar="(max-width: 1024px)" toolbarTarget="target-element">.toolbar prop media-query is valid. Also, an element with the toolbarTarget prop id must exist on the page for the toolbar to be applied.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.
<BentoSidebar>
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</li>
<li>Nav item 5</li>
<li>Nav item 6</li>
</ul>
<BentoSidebarToolbar toolbar="(max-width: 767px)" toolbarTarget="toolbar-target">
<ul>
<li>Toolbar Item 1</li>
<li>Toolbar Item 2</li>
</ul>
</BentoSidebarToolbar>
</BentoSidebar>
<div id="target-element"></div>
Bento components are highly interactive through their API. The BentoSidebar component API is accessible by passing a ref:
import React, {createRef} from 'react';
const ref = createRef();
function App() {
return (
<BentoSidebar ref={ref}>
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</li>
<li>Nav item 5</li>
<li>Nav item 6</li>
</ul>
</BentoSidebar>
);
}
The BentoSidebar API allows you to perform the following actions:
open() Opens the sidebar.
ref.current..open();
close() Closes the sidebar.
ref.current..close();
toggle() Toggles the sidebar open state.
ref.current..toggle(0);
The BentoSidebar component can be styled with standard CSS.
width of the bento-sidebar may be set to adjust the width from the preset 45px value.bento-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.To ensure the component renders how you want it to, be sure to apply a size to the component. These can be applied inline:
<BentoSidebar style={{width: '300px', height: '100%'}}>
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</li>
<li>Nav item 5</li>
<li>Nav item 6</li>
</ul>
</BentoSidebar>
Or via className:
<BentoSidebar className='custom-styles'>
<ul>
<li>Nav item 1</li>
<li>Nav item 2</li>
<li>Nav item 3</li>
<li>Nav item 4</li>
<li>Nav item 5</li>
<li>Nav item 6</li>
</ul>
</BentoSidebar>
.custom-styles {
height: 100%;
width: 300px;
}
When using <BentoSidebar>, keep in mind that your users will often view your page on mobile, 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.
<BentoSidebar> 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 BentoSidebar with a set z-index may cause the sidebar to appear below other elements (such as headers), breaking its functionality.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.
This prop is present on child <BentoSidebarToolbar toolbar="(media-query)" toolbarTarget="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 <BentoSidebarToolbar toolbar="(media-query)" toolbarTarget="elementID">, and accepts an id of an element on the page. The toolbarTarget prop 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.
FAQs
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Maintainers back GitHub’s npm security overhaul but raise concerns about CI/CD workflows, enterprise support, and token management.
Product
Socket Firewall is a free tool that blocks malicious packages at install time, giving developers proactive protection against rising supply chain attacks.
Research
Socket uncovers malicious Rust crates impersonating fast_log to steal Solana and Ethereum wallet keys from source code.