Skip to content

Instantly share code, notes, and snippets.

@pinei
Last active October 24, 2025 00:31
Show Gist options
  • Select an option

  • Save pinei/14545e81e8629eed72b55fce1cbd7822 to your computer and use it in GitHub Desktop.

Select an option

Save pinei/14545e81e8629eed72b55fce1cbd7822 to your computer and use it in GitHub Desktop.
A Carousel component for Quartz v4.5

Description

What is a Carousel Component?

A carousel (also known as a slider or image gallery) is a UI component that displays a series of content items (in this case, images) in a rotating fashion. Users can navigate through the content using:

  • Navigation arrows (previous/next buttons)
  • Dot indicators (click to jump to specific slides)
  • Keyboard navigation (arrow keys)
  • Touch/swipe gestures (on mobile devices)
  • Image modal (click images for full-screen view)

This Carousel component is a widget designed specifically for Quartz v4.5 static site generator. It provides an interactive slideshow experience that allows users to navigate through multiple images within a single container.

It is implemented as a transformer

Basic implementation

Create the following files in your Quartz project:

Transformer plugin:

quartz/plugins/transformers/carousel.ts

Update the index at quartz/plugins/transformers/index.ts adding the export of Carousel

export { Carousel } from "./carousel"

TypeScript script:

quartz/components/scripts/carousel.inline.ts

SCSS styles

quartz/components/styles/carousel.inline.scss

Configure Quartz

Add the Carousel transformer to your quartz.config.ts:

import { Carousel } from "./quartz/plugins/transformers/carousel"

export default defineConfig({
  transforms: {
    beforeSite: [
      // ... other transformers
      Carousel({ showDots: true }), // Add this line
    ],
  },
  // ... rest of your config
})

Run Quartz to ensure everything is properly set up:

npx quartz build --serve

How to use

Simple Carousel in Markdown

Use the tag in your Markdown files:

<Carousel>
<img src="image1.jpg" alt="Description of image 1"/>
<img src="image2.jpg" alt="Description of image 2"/>
<img src="image3.jpg" alt="Description of image 3"/>
</Carousel>

Initialization

The carousel automatically initializes when:

  • The page loads (via DOMContentLoaded event)
  • New content is dynamically added (via MutationObserver)
  • Navigation occurs in single-page applications (removed)

Navigation Methods

Users can navigate through slides using:

  • Mouse: Click prev/next buttons or dot indicators
  • Keyboard: Use left/right arrow keys when carousel is focused
  • Touch: Swipe left/right on mobile devices
  • Modal: Click any image to view in full-screen mode

Performance Features

  • Lazy initialization prevents unnecessary processing
  • Debounced observers avoid excessive DOM queries
  • Efficient event handling with passive listeners where appropriate
  • WeakSet caching prevents memory leaks and duplicate initialization
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment