Table of contents

Behavior
- Advancing to a specific slide
- Accessibility considerations for amp-carousel
Attributes
Styling
Supported Layouts for Slides
Validation

Important: this documentation is not applicable to your currently selected format stories!

amp-carousel

Description

Displays multiple similar pieces of content along a horizontal axis.

Required Scripts

<script async custom-element="amp-carousel" src="https://cdn.ampproject.org/v0/amp-carousel-0.1.js"></script>

Supported Layouts

fill fixed fixed-height flex-item intrinsic nodisplay responsive

A generic carousel for displaying multiple similar pieces of content along a horizontal axis; meant to be highly flexible and performant.

Behavior

Each of the amp-carousel component’s immediate children is considered an item in the carousel. Each of these nodes may also have arbitrary HTML children.

The carousel consists of an arbitrary number of items, as well as optional navigational arrows to go forward or backwards. For type="slides", the arrows moves one item at a time. For type="carousel", the arrows move one carousel's width forwards or backwards at a time.

The carousel advances between items if the user swipes or clicks an optional navigation arrow.

<amp-carousel
  width="450"
  height="300"
  layout="responsive"
  type="slides"
  role="region"
  aria-label="Basic carousel"
>
  <amp-img
    src="/static/inline-examples/images/image1.jpg"
    width="450"
    height="300"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image2.jpg"
    width="450"
    height="300"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image3.jpg"
    width="450"
    height="300"
  ></amp-img>
</amp-carousel>

Open this snippet in playground

Advancing to a specific slide

Setting a method for the on attribute on an element to tap:carousel-id.goToSlide(index=N) will, on user tap or click, advance a carousel with the "carousel-id" ID to the slide at index=N (the first slide is at index=0, the second slide is at index=1, and so on).

In the following example, we have a carousel of three images with preview buttons below the carousel. When a user clicks one of the buttons, the corresponding carousel item displays.

<amp-carousel
  id="carousel-with-preview"
  width="450"
  height="300"
  layout="responsive"
  type="slides"
  role="region"
  aria-label="Carousel with slide previews"
>
  <amp-img
    src="/static/inline-examples/images/image1.jpg"
    width="450"
    height="300"
    layout="responsive"
    alt="apples"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image2.jpg"
    width="450"
    height="300"
    layout="responsive"
    alt="lemons"
  ></amp-img>
  <amp-img
    src="/static/inline-examples/images/image3.jpg"
    width="450"
    height="300"
    layout="responsive"
    alt="blueberries"
  ></amp-img>
</amp-carousel>
<div class="carousel-preview">
  <button on="tap:carousel-with-preview.goToSlide(index=0)">
    <amp-img
      src="/static/inline-examples/images/image1.jpg"
      width="60"
      height="40"
      alt="apples"
    ></amp-img>
  </button>
  <button on="tap:carousel-with-preview.goToSlide(index=1)">
    <amp-img
      src="/static/inline-examples/images/image2.jpg"
      width="60"
      height="40"
      alt="lemons"
    ></amp-img>
  </button>
  <button on="tap:carousel-with-preview.goToSlide(index=2)">
    <amp-img
      src="/static/inline-examples/images/image3.jpg"
      width="60"
      height="40"
      alt="blueberries"
    ></amp-img>
  </button>
</div>

Open this snippet in playground

Accessibility considerations for `amp-carousel`

Autoplaying, and particularly infinitely looping, carousels can be very distracting and confusing for users - especially for users with cognitive impairments. In general, we recommend avoiding autoplaying carousels. While autoplaying carousels stop once the user has interacted with the carousel, consider also adding an explicit "Play/Pause" control.

By default, the <amp-carousel> is programmatically identified as a list when rendered (using role="list" on the container element, and role="listitem" on each item). However, for <amp-carousel type="slides">, no specific role is currently provided. As a result, it will not be obvious for assistive technology users reading/navigating through a page when they reach a carousel. We recommend including an explicit role="region" and a descriptive aria-label (either a generic aria-label="Carousel" or a more descriptive label such as aria-label="Latest news items") to <amp-carousel>.

Currently, an <amp-carousel type="slides"> carousel is declared as an ARIA live region (using aria-live="polite"), meaning that every time a new slide is shown, the entire content of the slide is announced by assistive technologies (such as screen readers). Due to the way carousels are initially rendered, this can also result in the carousel's content being announced in its entirety when a page is loaded. This also means that pages that contain an autoplay carousel will continuously announce whenever a slide auto-advances. There is currently no work-around for this issue.

Attributes

type	Specifies the display type for the carousel items, which can be: `carousel` (default): All slides are shown and are scrollable horizontally. This type supports only the following layouts: `fixed`, `fixed-height`, and `nodisplay`. `slides`: Shows a single slide at a time. This type supports the following layouts: `fill`, `fixed`, `fixed-height`, `flex-item`, `nodisplay`, and `responsive`.
height (required)	Specifies the height of the carousel, in pixels.
controls (optional)	Permanently displays left and right arrows for the user to navigate carousel items on mobile devices. By default, navigational arrows disappear after a few seconds on mobile. The visibility of arrows can also be controlled via styling, and a media query can be used to only display arrows at certain screen widths. On desktop, arrows are always displayed unless only a single child is present.
data-next-button-aria-label (optional)	Sets the aria-label for the `amp-carousel-button-next`. If no value is given, the aria-label defaults to 'Next item in carousel'.
data-prev-button-aria-label (optional)	Sets the aria-label for the `amp-carousel-button-prev`. If no value is given, the aria-label defaults to 'Previous item in carousel'.
data-button-count-format (optional)	A format string that looks like `(%s of %s)`, used as a suffix to the aria-label for `amp-carousel-button-next`/`amp-carousel-button-prev`. This provides information to users using a screen reader on their progress through the carousel. If no value is given, this defaults to '(%s of %s)'.
autoplay (optional)	Regularly advances to the next slide without user interaction. If the user manually changes slides, then autoplay is stopped. If present without a value: By default, advances a slide in 5000 millisecond intervals (5 seconds); this can be overridden by the `delay` attribute. Attaches the `loop` attribute to `amp-carousel` if `loop` is not already present. Requires at least 2 slides for autoplay to occur. Applies only to carousels with `type=slides`. If present with a value: Attaches the `loop` attribute to `amp-carousel` if `loop` is not already present. Removes the `loop` attribute after the requisite number of loops are made.
delay (optional)	Specifies the duration (in milliseconds) to delay advancing to the next slide when `autoplay` is enabled. Note that the minimum allowed value for `delay` is 1000 milliseconds.The `delay` attribute is only applicable to carousels with `type=slides`.
loop (optional)	Allows the user to advance past the first item or the final item. There must be at least 3 slides for looping to occur. The `loop` attribute is only applicable to carousels with `type=slides`. Example: Displays a slides carousel with controls, looping, and delayed autoplay <amp-carousel type="slides" width="450" height="300" controls loop autoplay delay="3000" data-next-button-aria-label="Go to next slide" data-previous-button-aria-label="Go to previous slide" role="region" aria-label="Looping carousel"> <amp-img src="/static/inline-examples/images/image1.jpg" width="450" height="300"></amp-img> <amp-img src="/static/inline-examples/images/image2.jpg" width="450" height="300"></amp-img> <amp-img src="/static/inline-examples/images/image3.jpg" width="450" height="300"></amp-img> </amp-carousel> Open this snippet in playground
common attributes	This element includes common attributes extended to AMP components.

Styling

You may use the amp-carousel element selector to style it freely.
You may use the .amp-carousel-slide class selector to target carousel items.
The visual state of an amp-carousel button when it's disabled is hidden.
By default, .amp-carousel-button uses an inlined SVG as the background-image of the buttons. You may override this with your own SVG or image as in the example below.

Example: Default .amp-carousel-button inlined SVG

.amp-carousel-button-prev {
  left: 16px;
  background-image: url('data:image/svg+xml;charset=utf-8,%3Csvg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="%23fff"%3E%3Cpath d="M15 8.25H5.87l4.19-4.19L9 3 3 9l6 6 1.06-1.06-4.19-4.19H15v-1.5z"/%3E%3C/svg%3E');
}

Example: Overriding the default .amp-carousel-button inlined SVG

.amp-carousel-button-prev {
  left: 5%;
  background-image: url('data:image/svg+xml;charset=utf-8,%3Csvg xmlns="http://www.w3.org/2000/svg" width="18" height="18" fill="%23fff"%3E%3Cpath d="M11.56 5.56L10.5 4.5 6 9l4.5 4.5 1.06-1.06L8.12 9z"  /%3E%3C/svg%3E');
}

Note that the SVG content needs to have certain characters, including <, > and # encoded. This can be done using a tool like SVGO or using encodeURIComponent.

Supported Layouts for Slides

As noted above, the type="slides" designation on amp-carousel 0.1 supports the following layouts: fill, fixed, fixed-height, flex-item, nodisplay, and responsive.

Publishers should be aware that while this mode explicitly supports fixed layout sizes, it also employs display: flex; in its styling. In other words nested elements can have layout=fixed sizing, though via styling it only respects absolute width up to 100%. One way to workaround this limitation is by using flex-shrink: 0 on any fixed layout slides.

For an accessible and smooth user experience, it is generally good practice when using type="slides" that all children of that carousel and the carousel itself share the same dimensional ratios as well as the same layout type.

Validation

See amp-carousel 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

amp-carousel 0.2 0.1