AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

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 is available experimentally and only works on the latest browsers. Read our Blog Post for information on future plans and how to get involved!

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>

To make Bento components load event faster, eliminating need for the AMP runtime script is a high priority for Bento AMP. Follow our progress on the Bento roadmap.

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.

For the best rendering performance inline the Bento component CSS directly into the page to avoid a render-blocking request to 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>

Bento components don't support AMP's layout system.

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:

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.