<carou-scroll> Web Component

<carou-scroll> is a zero-dependency web component to add next and previous buttons to a scrollable container. I use it to share exported Keynote slides (as images) on my blog posts.

Some inspiration from the W3C WAI Carousel Tutorial (though this isn’t technically a carousel).

• Source code on GitHub
• Demo

More real-world demos of Keynote slides:

• The Good, The Bad, The Web Components (and the post source code)
• The Eleventy V2.0 Release, A Talk at the Eleventy Meetup (and the post source code)
• Eleventy: Build vs. Serverless vs. Edge (and the post source code)

Features #

• Interaction compatible with scroll or touch.
• No layout shift. Make sure you include the CSS snippet!
• (Optional) Smooth scrolling with scroll-behavior: smooth.
• (Optional) loop attribute to enable looping around from start/end.
• (Optional) Next/Previous buttons can be placed anywhere in the document.
• (Optional) <output> element can accessibly announce the current slide number (out of total number of slides).

Usage #

Installation #

You can install via npm or download the carouscroll.js JavaScript file manually.

npm install @zachleat/carouscroll --save

Add carouscroll.js to your site’s JavaScript assets.

Markup #

The CSS here is crucial to reduce Layout Shift (CLS), set the aspect ratio of the slides, and to avoid loading loading="lazy" images on off-screen slides.

<style>
carou-scroll {
	display: flex;
	overflow-x: scroll;
	overflow-y: hidden;
}
carou-scroll > * {
	min-width: 100%;
	 /* Customize this as needed */
	aspect-ratio: 16/9;
}
</style>

<script type="module" src="carouscroll.js"></script>

<carou-scroll id="my-scroller">
	<img loading="lazy" src="…" alt="…">
	<img loading="lazy" src="…" alt="…">
	<!-- … -->
</carou-scroll>

More examples #

Add buttons (optional) #

For maximum flexibility, these buttons can be placed anywhere in the document and are tied by an id back to the parent scroller.

Make sure you think about the before/after JavaScript experience here. This component will remove disabled for you but you can add additional styling via your own CSS: carou-scroll:defined {}.

<button type="button" disabled data-carousel-previous="my-scroller">Previous</button>
<button type="button" disabled data-carousel-next="my-scroller">Next</button>

Add output (optional) #

This will update (and accessibly announce) a current status element with e.g. Slide 1 of 10 text.

For maximum flexibility, this element can be placed anywhere in the document and is tied by an id back to the parent scroller.

<output data-carousel-output="my-scroller"></output>

<!-- Or customize with your own markup -->
<output data-carousel-output="my-scroller" lang="ko">슬라이드 <span data-carousel-output-current>1</span>/<span data-carousel-output-total>10</span></output>

Make it loop around (optional) #

Add the loop attribute.

<carou-scroll id="my-scroller" loop>

Smooth scrolling CSS (optional) #

carou-scroll {
	scroll-behavior: smooth;
}