Use Bento components in non-AMP pages
Important: this documentation is not applicable to your currently selected format stories!
Use AMP's well-tested, cross-browser compatible and accessible components anywhere on the web with Bento AMP. Bento AMP 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. Bento also lets you test out AMP components to see if the path to valid AMP is right for your use case.
Bento components are still in development and APIs might change. However, they're available for experimental use in a developer preview. This means you must enable the experimental flag either in the document or the console. This is no different from other experiments in AMP.
Keep an eye out for announcements and updates. While Bento AMP is in developer preview, the team will continue to make necessary changes to the API to improve features.
Enable Bento Experiment
Bento components are available experimentally and you must enable experimental features.
Enable the Bento experiment by including the script below:
<script>
(self.AMP = self.AMP || []).push(function (AMP) {
AMP.toggleExperiment('bento', true);
});
</script>
Import AMP runtime and Bento component script
You must include the AMP runtime script and import the component script for each individual Bento component desired. We also recommend importing the component's CSS stylesheet for the best user experience.
<!-- AMP runtime script -->
<script async src="https://cdn.ampproject.org/v0.js"></script>
<!-- Bento component stylesheet -->
<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-bento-component-name-1.0.css">
<!-- Bento component script -->
<script async custom-element="amp-bento-component-name" src="https://cdn.ampproject.org/v0/amp-bento-component-name-1.0.js"></script>
Read each Bento component’s reference documentation for implementation details.
Layout and styling
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.
cdn.ampproject.org
on page load. <link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/amp-bento-component-name-1.0.css">
<style>
custom styles
</style>
You can style and layout Bento components using standard CSS. Here are a few strategies on how you can layout Bento components using CSS:
Fixed layout
.fixed-layout {
display: inline-block;
width: xpx;
height: xpx;
}
Responsive layout with a fixed aspect ratio
.responsive-layout {
display: block;
aspect-ratio: width/height;
}
aspect-ratio
is a new CSS feature. If you are not seeing the desired results, try this fallback method. Fill layout
Either:
.fill-layout {
position: absolute;
top: 0;
left: 0;
right: 0;
bottom: 0;
}
Or:
.fill-layout {
width: 100%;
height: 100%;
}
Depending on element context.
Flex layout
.flex-layout {
display: block;
flex: 1 1 auto;
}
Interacting with Bento components
Bento components have individual APIs that grant access to component actions and events. Access to component APIs and invoking events use the following syntax and required for each desired component:
await customElements.whenDefined('amp-bento-component');
const element = document.querySelector('amp-bento-component');
const api = await element.getApi();
api.callMethod();
Fully valid AMP installs event listeners on elements via the on
attribute with the event and responding action as values. Bento AMP does not rely on this attribute. Instead, use component APIs to manage and react to events.
The example below triggers amp-accordion
's toggle action when the user clicks the "Toggle Accordion" button.
<head>
<script async src="https://cdn.ampproject.org/v0.js"></script>
<link
rel="stylesheet"
type="text/css"
href="https://cdn.ampproject.org/v0/amp-accordion-1.0.css"
/>
<script
async
custom-element="amp-accordion"
src="https://cdn.ampproject.org/v0/amp-accordion-1.0.js"
></script>
</head>
<script>
(self.AMP = self.AMP || []).push(function (AMP) {
AMP.toggleExperiment('bento', true);
});
</script>
<amp-accordion id="my-accordion" disable-session-states>
<section>
<h2>Section 1</h2>
<p>Content in section 1.</p>
</section>
<section>
<h2>Section 2</h2>
<div>Content in section 2.</div>
</section>
<section>
<h2>Section 3</h2>
<img
width="150px"
height="100px"
src="https://amp.dev/static/samples/img/product2_1024x682.jpg"
/>
</section>
</amp-accordion>
<button id="toggle">Toggle Accordion</button>
<script>
const toggleAccordion = async () => {
await customElements.whenDefined('amp-accordion');
const accordion = document.querySelector('#my-accordion');
const api = await accordion.getApi();
api.toggle();
};
const toggleButton = document.querySelector('#toggle');
toggleButton.addEventListener('click', toggleAccordion);
</script>
Read each component's reference documentation for a full list of available actions and events.
Available Bento components
Bento supported AMP components are listed below:
- amp-accordion
- amp-base-carousel
- amp-inline-gallery
- amp-stream-gallery
- amp-date-countdown
- amp-date-display
- amp-fit-text
- amp-instagram
- amp-lightbox
- amp-selector
- amp-social-share
- amp-timeago
- Video components
Bento in action
The example below demonstrates how to include amp-base-carousel
and use the next
and prev
actions in a non-AMP HTML page.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<title>Bento Carousel Example</title>
<script async src="https://cdn.ampproject.org/v0.js"></script>
<script
async
custom-element="amp-base-carousel"
src="https://cdn.ampproject.org/v0/amp-base-carousel-1.0.js"
></script>
<script>
(self.AMP = self.AMP || []).push(function (AMP) {
AMP.toggleExperiment('bento', true);
});
</script>
<style>
amp-base-carousel {
display: block;
height: 100px;
width: 150px;
overflow: hidden;
}
</style>
</head>
<body>
<amp-base-carousel
id="my-carousel"
controls="never"
loop
auto-advance
auto-advance-interval="5000"
>
<img
width="150px"
height="100px"
src="https://amp.dev/static/samples/img/green_apple_1_1024x682.jpg"
/>
<img
width="150px"
height="100px"
src="https://amp.dev/static/samples/img/golden_apple1_1024x682.jpg"
/>
<img
width="150px"
height="100px"
src="https://amp.dev/static/samples/img/product2_1024x682.jpg"
/>
</amp-base-carousel>
<button id="previous-button">Previous Slide</button>
<button id="next-button">Next Slide</button>
<script>
async function nextSlide() {
const carousel = document.querySelector('amp-base-carousel');
await customElements.whenDefined('amp-base-carousel');
const api = await carousel.getApi();
api.next();
}
async function prevSlide() {
const carousel = document.querySelector('amp-base-carousel');
await customElements.whenDefined('amp-base-carousel');
const api = await carousel.getApi();
api.prev();
}
const nextButton = document.querySelector('#next-button');
const prevButton = document.querySelector('#previous-button');
nextButton.addEventListener('click', nextSlide);
prevButton.addEventListener('click', prevSlide);
</script>
</body>
</html>
Working with experiments
Bento AMP is in experimental mode and available through the developer preview. The AMP team welcomes developer feedback through GitHub and our Slack channel. Please reach out with any questions or issues.
Currently, Bento requires use of the latests browsers, but will support more versions at production release.
Page experience
Bento components are designed to be highly performant and contribute to an excellent page experience. Developers are highly encouraged to file issues if they see contradictory results.
AMP caches and validation
Using Bento components during the limited developer preview makes your web page an invalid AMP page. Therefore, your doc and any Bento components are not served by any AMP caches.
-
Written by @CrystalOnScript