AMP

Important: this component does not support your currently selected format email!

amp-base-carousel

A generic carousel for displaying multiple similar pieces of content along a horizontal or vertical axis.

Availability
Experimental; You must turn on the amp-base-carousel experiment to use this component.
Required Script <script async custom-element="amp-base-carousel" src="https://cdn.ampproject.org/v0/amp-base-carousel-0.1.js"></script>
Supported Layouts fill, fixed, fixed-height, flex-item, intrinsic, nodisplay, and responsive.
Examples amp-carousel example

Behavior

Each of the amp-base-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 a single item.

The carousel advances between items if the user swipes or uses the customizable arrow buttons.

Attributes

Using Media Queries

The attributes for <amp-base-carousel> can be configured to use different options based on a media query. You can also use a value without any media queries. The format looks like:

<amp-base-carousel
  attr-name="(min-width: 1000px) valueOne, (min-width: 600px) valueTwo, defaultValue"
></amp-base-carousel>

The media queries are evaluated from left to right, with the first matching media query being used. A default value (without a media query) is required. In this case, if the page has a screen width of 1000px or more, valueOne is used. If the width is between 999px and 600px, valueTwo is used. When it is 599px or smaller, defaultValue is used.

Configuration Options

Number of Visible Slides

mixed-length Either true or false, defaults to false. When true, uses the existing width (or height when horizontal) for each of the slides. This allows for a carousel with slides of different widths to be used.
visible-count A number, defaults to 1. Determines how many slides should be shown at a given time. Fractional values can be used to make part of a(n) additional slide(s) visible. This option is ignored when mixed-length is true.
advance-count A number, defaults to 1. Determines how many slides the carousel will advance when advancing using the previous or next arrows. This is useful when specifying the visible-count attribute.

Auto Advance

auto-advance Either true or false, defaults to false. Automatically advances the carousel to the next slide based on a delay. If the user manually changes slides, then the auto advance is stopped. Note that if loop is not enabled, when reaching the last item, the auto advance will move backwards to the first item.
auto-advance-count A number, defaults to 1. Determines how many slides the carousel will advance when automatically advancing. This is useful when specifying the visible-count attribute.
auto-advance-interval A number, defaults to 1000. Specifies the amount of time, in milliseconds, between subsequent automatic advances of the carousel.
auto-advance-loops A number, defaults to . The number of times the carousel should advance through the slides before stopping.

Snapping

snap Either true or false, defaults to true. Determines whether or not the carousel should snap on slides when scrolling.
snap-align Either start or center. When start aligning, the start of a slide (e.g. the left edge, when horizontal aligning) is aligned with the start of a carousel. When center aligning, the center of a slide is aligned with the center of a carousel.
snap-by A number, defaults to 1. This determines the granularity of snapping and is useful when using visible-count. This

Miscellaneous

slide A number, defaults to 0. This determines the initial slide shown in the carousel. This may be used with amp-bind to control which slide is currently showing.
loop Either true or false, defaults to true. When true, the carousel will allow the user to move from the first item back to the last item and visa versa. There must be at least three slides present for looping to occur.
horizontal Either true or false, defaults to true. When true the carousel will lay out horizontally, with the user being able to swipe left and right. When false, the carousel lays out vertically, with the user being able to swipe up and down.
common attributes This element includes common attributes extended to AMP components.

Events

slideChange This event is triggered when the index displayed by the carousel has changed. The new index is available via event.index.

Actions

next Moves the carousel forwards by advance-count slides.
prev Moves the carousel backwards by advance-count slides.
goToSlide Moves the carousel to the slide specified by the index argument.

Styling

  • You may use the amp-base-carousel element selector to style the carousel freely.

Customizing Arrow Buttons

Arrow buttons can be customized by passing in your own custom markup. For example, you can recreate the default styling with the following HTML and CSS:

.carousel-prev,
.carousel-next {
  filter: drop-shadow(0px 1px 2px #4a4a4a);
  width: 40px;
  height: 40px;
  padding: 20px;
  background-color: transparent;
  border: none;
  outline: none;
}

.carousel-prev {
  background-image: url('data:image/svg+xml;charset=utf-8,<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path  d="M14,7.4 L9.4,12 L14,16.6" fill="none" stroke="#fff" stroke-width="2px" stroke-linejoin="round" stroke-linecap="round" /></svg>');
}

.carousel-next {
  background-image: url('data:image/svg+xml;charset=utf-8,<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><path  d="M10,7.4 L14.6,12 L10,16.6" fill="none" stroke="#fff" stroke-width="2px" stroke-linejoin="round" stroke-linecap="round" /></svg>');
}
<amp-base-carousel >
  <div>first slide</div><button slot="next-arrow" class="carousel-next" aria-label="Next"></button>
  <button
    slot="prev-arrow"
    class="carousel-prev"
    aria-label="Previous"
  ></button>
</amp-base-carousel>

If you want more customization for the arrow buttons, you can use the next and prev actions. For example, if you want to place buttons under the carousel and use the words "Previous" and "Next" instead of having them in the default location, you can use the following HTML:

  <amp-base-carousel id="carousel-1" ><div slot="next-arrow"></div>
    <div slot="prev-arrow"></div>
  </amp-carousel>
  <button on="tap:carousel-1.prev()">Previous</button>
  <button on="tap:carousel-1.next()">Next</button>

Usage Notes

RTL

<amp-base-carousel> currently requires that you let it know when it is in an right-to-left (rtl) context (e.g. Arabic, Hebrew pages). While the carousel will generally work without this, there may be a few bugs. You can let the carousel know that it should operate as rtl as follows:

<amp-base-carousel dir="rtl" ></amp-base-carousel>

If the carousel is in a RTL context, and you want the carousel to operate as LTR, you can explicitly set the dir="ltr" on the carousel.

Slide layout

Slides are automatically sized by the carousel when not specifying mixed-lengths. You should give the slides layout="flex-item":

<amp-base-carousel >
  <amp-img layout="flex-item" src="…"></amp-img>
</amp-base-carousel>

The slides have a default height of 100% when the carousel is laid out horizontally. This can easily be changed with CSS or by using layout="fixed-height". When specifying the height, the slide will be vertically centered within the carousel.

If you want to horizontally center your slide content, you will want to create a wrapping element, and use that to center the content.

Number of Visible Slides

When changing the number of visible slides using visible-slides, in response to a media query, you will likely want to change the aspect ratio of the carousel itself to match the new number of visible slides. For example, if you want to show three slides at a time with a one by one aspect ratio, you would want an aspect ratio of three by one for the carousel itself. Similiarly, with four slides at a time you would want an aspect ratio of four by one. In addition, when changing visible-slides, you likely want to change advance-count.

<!-- Using an aspect ratio of 3:2 for the slides in this example. -->
<amp-base-carousel
  layout="responsive"
  width="3"
  height="1"
  heights="(min-width: 600px) calc(100% * 4 * 3 / 2), calc(100% * 3 * 3 / 2)"
  visible-count="(min-width: 600px) 4, 3"
  advance-count="(min-width: 600px) 4, 3"
>
  <amp-img layout="flex-item" src="…"></amp-img></amp-base-carousel>

Validation

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