Carousel

<quiet-carousel>

stable

since 1.0

A carousel component that displays content in a scrollable horizontal slider with navigation controls.

<quiet-carousel label="Example slides" id="carousel__overview">
  <quiet-carousel-item>Slide 1</quiet-carousel-item>
  <quiet-carousel-item>Slide 2</quiet-carousel-item>
  <quiet-carousel-item>Slide 3</quiet-carousel-item>
  <quiet-carousel-item>Slide 4</quiet-carousel-item>
  <quiet-carousel-item>Slide 5</quiet-carousel-item>
</quiet-carousel>

<style>
  #carousel__overview {
    quiet-carousel-item {
      background: var(--quiet-neutral-fill-soft);
      color: var(--quiet-text-muted);
      font-size: 2rem;
      font-weight: 500;
    }
  }
</style>

<script>
  const carousel = document.getElementById('carousel__overview');

  carousel.addEventListener('quiet-item-change', event => console.log(event.detail.index));
</script>

Examples Jump to heading

Providing content Jump to heading

Slot in <quiet-carousel> items with the content you'd like to show in each slide. Images work well, but you can add just about any content, including interactive elements such as links and buttons.

By default, the carousel spans 100% of the width and uses a 16/9 aspect ratio. You can adjust this using the --aspect-ratio custom property as shown below. For full control over the width and height, you can target the items part using CSS.

A gray and white cat sleeps on a blanket with evening lights in the background

Kittens dream of chasing moonbeams across the sky.

Learn more

Kittens nap to plot their next playful adventure.

Learn more

An orange cat sleeps peacefully at the edge of a bed

Kittens snooze, dreaming of fluffy clouds to leap.

Learn more

A sleepy cat looks up in dim, hazy purple lighting

Kittens yawn, scheming to pounce on twilight stars.

Learn more

A gray cat curled up but keeping an eye out

Kittens curl up, plotting to unravel yarn mysteries.

Learn more

<quiet-carousel label="Example slides" id="carousel__providing">
  <quiet-carousel-item>
    <quiet-card>
      <img slot="media" src="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray and white cat sleeps on a blanket with evening lights in the background">
      <p>Kittens dream of chasing moonbeams across the sky.</p>
      <quiet-button slot="footer">Learn more</quiet-button>
    </quiet-card>    
  </quiet-carousel-item>

  <quiet-carousel-item>
    <quiet-card>
      <img slot="media" src="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A kitten sleeps peacefully on the floor">
      <p>Kittens nap to plot their next playful adventure.</p>
      <quiet-button slot="footer">Learn more</quiet-button>
    </quiet-card>    
  </quiet-carousel-item>

  <quiet-carousel-item>
    <quiet-card>
      <img slot="media" src="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="An orange cat sleeps peacefully at the edge of a bed">
      <p>Kittens snooze, dreaming of fluffy clouds to leap.</p>
      <quiet-button slot="footer">Learn more</quiet-button>
    </quiet-card>    
  </quiet-carousel-item>

  <quiet-carousel-item>
    <quiet-card>
      <img slot="media" src="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A sleepy cat looks up in dim, hazy purple lighting"> 
      <p>Kittens yawn, scheming to pounce on twilight stars.</p> 
      <quiet-button slot="footer">Learn more</quiet-button>
    </quiet-card>    
  </quiet-carousel-item> 

  <quiet-carousel-item>
    <quiet-card>
      <img slot="media" src="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray cat curled up but keeping an eye out">  
      <p>Kittens curl up, plotting to unravel yarn mysteries.</p>
      <quiet-button slot="footer">Learn more</quiet-button>
    </quiet-card>    
  </quiet-carousel-item>  
</quiet-carousel>

<style>
  #carousel__providing {
    --aspect-ratio: 3 / 4;
    --item-height: fit-content;
    max-width: 360px;
  }
</style>

Setting the initial item Jump to heading

Use the active-index attribute to set the item that should show initially. The index is zero-based, so the first slide has an index of 0, the second slide has an index of 1, etc.

<quiet-carousel active-index="2" id="carousel__index">
  <quiet-carousel-item>Slide 1</quiet-carousel-item>
  <quiet-carousel-item>Slide 2</quiet-carousel-item>
  <quiet-carousel-item>Slide 3</quiet-carousel-item>
  <quiet-carousel-item>Slide 4</quiet-carousel-item>
  <quiet-carousel-item>Slide 5</quiet-carousel-item>
</quiet-carousel>

<style>
  #carousel__index {
    quiet-carousel-item {
      background: var(--quiet-neutral-fill-soft);
      color: var(--quiet-text-muted);
      font-size: 2rem;
      font-weight: 500;
    }
  }
</style>

You can hide the previous/next buttons by adding the without-nav attribute. To hide the pagination dots, use the without-pagination attribute.

<div id="carousel__without">
  <div class="controls">
    <quiet-switch checked label="With nav"></quiet-switch><br>
    <quiet-switch checked label="With pagination"></quiet-switch>
  </div>
    
  <quiet-carousel>
    <quiet-carousel-item>Slide 1</quiet-carousel-item>
    <quiet-carousel-item>Slide 2</quiet-carousel-item>
    <quiet-carousel-item>Slide 3</quiet-carousel-item>
    <quiet-carousel-item>Slide 4</quiet-carousel-item>
    <quiet-carousel-item>Slide 5</quiet-carousel-item>
  </quiet-carousel>
</div>

<script>
  const container = document.getElementById('carousel__without');
  const carousel = container.querySelector('quiet-carousel');
  const navSwitch = container.querySelectorAll('quiet-switch')[0];
  const paginationSwitch = container.querySelectorAll('quiet-switch')[1];

  navSwitch.addEventListener('input', () => {
    carousel.toggleAttribute('without-nav', !navSwitch.checked);
  });

  paginationSwitch.addEventListener('input', () => {
    carousel.toggleAttribute('without-pagination', !paginationSwitch.checked);
  });
</script>

<style>
  #carousel__without {
    display: flex;
    flex-direction: column;
    gap: 1rem;

    .controls {
      display: flex;
      gap: 1rem; 
      justify-content: center;
    }    

    quiet-carousel-item {
      background: var(--quiet-neutral-fill-soft);
      color: var(--quiet-text-muted);
      font-size: 2rem;
      font-weight: 500;
    }
  }
</style>

Varying widths Jump to heading

You can create carousel items with various widths and max widths by applying the appropriate styles to each item.

<quiet-carousel label="Cat nap slideshow" id="carousel__varying">
  <quiet-carousel-item>Slide 1</quiet-carousel-item>
  <quiet-carousel-item style="max-width: 350px;">Slide 2</quiet-carousel-item>
  <quiet-carousel-item style="max-width: 200px;">Slide 3</quiet-carousel-item>
  <quiet-carousel-item>Slide 4</quiet-carousel-item>
  <quiet-carousel-item style="max-width: 450px;">Slide 5</quiet-carousel-item>
</quiet-carousel>

<style>
  #carousel__varying {
    quiet-carousel-item {
      background: var(--quiet-neutral-fill-soft);
      color: var(--quiet-text-muted);
      font-size: 2rem;
      font-weight: 500;
    }
  }
</style>

Styling carousels Jump to heading

Carousels come with a simple, minimal appearance. Feel free to customize them with your own styles.

<quiet-carousel id="carousel__styling">
  <quiet-carousel-item>
    <img src="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray and white cat sleeps on a blanket with evening lights in the background">
  </quiet-carousel-item>
  <quiet-carousel-item>
    <img src="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A kitten sleeps peacefully on the floor">
  </quiet-carousel-item>
  <quiet-carousel-item>
    <img src="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="An orange cat sleeps peacefully at the edge of a bed">
  </quiet-carousel-item>
  <quiet-carousel-item>
    <img src="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A sleepy cat looks up in dim, hazy purple lighting">
  </quiet-carousel-item>  
  <quiet-carousel-item>
    <img src="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=1000&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D" alt="A gray cat curled up but keeping an eye out">
  </quiet-carousel-item>  
</quiet-carousel>

<style>
  #carousel__styling {
    --dot-size: .75rem;
    --dot-color: #fff4;
    --dot-active-color: white;

    &::part(items) {
      gap: .5rem;
    }

    /* Previous & next buttons */
    &::part(previous-button),
    &::part(next-button) {
      position: absolute;
      top: 0;
      bottom: 0;
      width: 5rem;
      height: 100%;
      border-radius: var(--quiet-border-radius);
      font-size: 1.5rem;
      background: none;
      color: white;
    }

    &::part(previous-button) {
      left: 0;
    }

    &::part(next-button) {
      right: 0;
    }

    &::part(previous-button):disabled,
    &::part(next-button):disabled {
      display: none;
    }

    /* Pagination container */
    &::part(pagination) {
      position: absolute;
      bottom: 3rem;
      width: 100%;
      justify-content: center;
    }

    &::part(pagination-dot):focus-visible {
      outline-width: 1.5px;
      outline-offset: 2px;
      outline-color: var(--quiet-text-muted);
    }
  }
</style>

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN

npm

To manually import <quiet-carousel> from the CDN, use the following code.

import 'https://cdn.jsdelivr.net/npm/@quietui/quiet-browser@1.0.0/dist/components/carousel/carousel.js';

To manually import <quiet-carousel> from npm, use the following code.

import '@quietui/quiet/dist/components/carousel/carousel.js';

Slots Jump to heading

Carousel supports the following slots. Learn more about using slots

Name	Description
(default)	The default slot for carousel items.

Properties Jump to heading

Carousel has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property / Attribute	Description	Type	Default
`label`	A custom label for the carousel. This won't be visible, but it will be read to assistive devices.	`string`	`''`
`activeIndex` `active-index`	The current active item index.	`number`	`0`
`withoutNav` `without-nav`	Hides navigation buttons.	`boolean`	`false`
`withoutPagination` `without-pagination`	Hides pagination dots.	`boolean`	`false`

Methods Jump to heading

Carousel supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name	Description	Arguments
`scrollToIndex()`	Navigate to the specified item.	`index: number, scrollBehavior: ScrollBehavior`
`scrollToNext()`	Navigate to the next item	`scrollBehavior: ScrollBehavior`
`scrollToPrevious()`	Navigate to the previous item	`scrollBehavior: ScrollBehavior`

Events Jump to heading

Carousel dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name	Description
`quiet-item-change`	Emitted when the active item changes and the slide has been fully scrolled into view.

CSS custom properties Jump to heading

Carousel supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name	Description	Default
`--aspect-ratio`	The aspect ratio of the carousel. By default, carousels render 100% wide, so this helps retain proportions across various devices. Gets applied to the `items` part.	`16/9`
`--item-gap`	The gap between items in the carousel.	`2rem`
`--dot-size`	The size of each pagination dot.	`0.875em`
`--dot-gap`	The size of the gap between pagination dots.	`0.5em`
`--dot-color`	The color of inactive pagination dots.	`var(--quiet-neutral-fill-soft)`
`--dot-active-color`	The color of active pagination dots.	`var(--quiet-neutral-fill-loud)`

CSS parts Jump to heading

Carousel exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name	Description	CSS selector
`items`	The scrollable container that holds the carousel items.	`::part(items)`
`controls`	The container that surrounds nav buttons and pagination.	`::part(controls)`
`previous-button`	The previous button.	`::part(previous-button)`
`next-button`	The next button.	`::part(next-button)`
`pagination`	The container for the pagination dots.	`::part(pagination)`
`pagination-dot`	Each individual pagination dot.	`::part(pagination-dot)`
`pagination-dot-active`	The active pagination dot.	`::part(pagination-dot-active)`

Custom States Jump to heading

Carousel has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name	Description	CSS selector
`scrolling`	Applied when the carousel is scrolling.	`:state(scrolling)`

Dependencies Jump to heading

Carousel automatically imports the following elements. Sub-dependencies are also included in this list.

Carousel

Examples Jump to heading #

Providing content Jump to heading #

Setting the initial item Jump to heading #

Hiding navigation Jump to heading #

Varying widths Jump to heading #

Styling carousels Jump to heading #

API Jump to heading #

Importing Jump to heading #

Slots Jump to heading #

Properties Jump to heading #

Methods Jump to heading #

Events Jump to heading #

CSS custom properties Jump to heading #

CSS parts Jump to heading #

Custom States Jump to heading #

Dependencies Jump to heading #

Examples Jump to heading

Providing content Jump to heading

Setting the initial item Jump to heading

Hiding navigation Jump to heading

Varying widths Jump to heading

Styling carousels Jump to heading

API Jump to heading

Importing Jump to heading

Slots Jump to heading

Properties Jump to heading

Methods Jump to heading

Events Jump to heading

CSS custom properties Jump to heading

CSS parts Jump to heading

Custom States Jump to heading

Dependencies Jump to heading