Carousel

READ FIRST
Carousels can be a nice touch, especially if you don't want to lengthen the page with the content you want to add, but not all content is right to go in a carousel. UX research has found more often than not that carousels provide a poor user experience because they are implemented poorly and especially because the wrong content was contained within. In general, you should only use a carousel if the information inside is largely superficial and not critical to the page. In other words, nothing important should go inside the carousel that you need your users to see or interact with.

Basics

The carousel consists of three parts: the carousel container, the carousel(s) and the controls. A carousel container is usually a <div id="some-unique-id-here">.

The carousel(s) is a nested <div class="carousel"> or <div class="carousel-inner"> (the latter form is deprecated). Each immediate child element of the carousel is a slide. You can have more than one carousel inside of a container, but they must have the same number of children (read: they can be different children but must be same number/length) or it won't initialize and you'll be left with a mess.

The controls are the custom element with the ID of the carousel container <ap-carousel data-container-id="some-unique-id-here"> which can be nested inside the carousel container or be outside of it elsewhere on the page. If the height of your carousel is going to change (various lines of text or varying image heights), I recommend you seat the controls above the carousel.

Example

Copy
html
<ap-carousel data-container-id="carousel-container-1"></ap-carousel>
<div id="carousel-container-1">
    <div class="carousel">
        <p>Slide 1</p>
        <div>Slide 2</div>
        <img
            src="/assets/images/favicons/favicon.svg"
            alt="Slide 3"
            width="41.154"
            height="41.154"
        />
    </div>
</div>

OR for multiple carousels…

<ap-carousel data-container-id="carousel-1"></ap-carousel>
<div id="carousel-1">
    <div class="carousel">
        <p>Slide 1</p>
        <div>Slide 2</div>
        <img
            src="/assets/images/favicons/favicon.svg"
            alt="Slide 3"
            width="41.154"
            height="41.154"
        />
    </div>
    <div class="carousel">
        <p>Author for Slide 1</p>
        <p>Author for Slide 2</p>
        <p>Artist for Slide 3</p>
    </div>
</div>
Expand

OR for multiple carousels…

Smooth Scrolling

If you want to enable smooth scrolling, you just need to add the data-smooth-scroll attribute to the custom element. This property respects users who have the "reduced motion" setting turned on in their browsers/devices, and will not turn on smooth scrolling for those users.

Example

Copy
html
<ap-carousel
    data-container-id="carousel-container-2"
    data-smooth-scroll
></ap-carousel>
<div id="carousel-container-2">
    <div class="carousel">
        <p>Slide 1</p>
        <div>Slide 2</div>
        <img
            src="/assets/images/favicons/favicon.svg"
            alt="Slide 3"
            width="41.154"
            height="41.154"
        />
    </div>
</div>
Expand

Auto Scrolling

If you would like to have the carousel turn automatically, add the data-auto-scroll-interval attribute to the custom element with a number value representing seconds per slide before it changes to the next one. Ensure the content you put in is largely visual, not intricate, and does not contain more than a few highly visible words per slide, especially if you spend less than 5 seconds on each slide.

The moment a user clicks on the controls is the moment the auto scrolling stops.

Example

Copy
html
<ap-carousel
    data-container-id="carousel-container-3"
    data-auto-scroll-interval="4"
></ap-carousel>
<div id="carousel-container-3">
    <div class="carousel">
        <p>Slide 1</p>
        <div>Slide 2</div>
        <img
            src="/assets/images/favicons/favicon.svg"
            alt="Slide 3"
            width="41.154"
            height="41.154"
        />
    </div>
</div>
Expand

Combining Auto and Smooth Scroll

You can combine bnoth scrolling methods by adding their respective attributes to the custom element.

Example

Copy
html
<ap-carousel
    data-container-id="carousel-container-4"
    data-smooth-scroll
    data-auto-scroll-interval="4"
></ap-carousel>
<div id="carousel-container-4">
    <div class="carousel">
        <p>Slide 1</p>
        <div>Slide 2</div>
        <img
            src="/assets/images/favicons/favicon.svg"
            alt="Slide 3"
            width="41.154"
            height="41.154"
        />
    </div>
</div>
Expand