Skip to content
Español

Navigate

Español

Type to search. Press Escape to close.

    Components · js

    Carousel

    A slideshow built on a list. The server sends slides in a horizontally scrolling track with scroll snapping, dots as plain anchor links and hidden buttons; that already works everywhere. On init the dots become tabs, the slides become panels, the buttons appear and the track is driven by transforms: slide with a parallax caption, crossfade, or a cinema mode that slowly zooms the active media. Autoplay draws a progress bar, pauses on hover, focus and hidden tabs, and never starts when the reader prefers reduced motion.

    CSS: css/components/carousel.css (in ivolt.css). JS: @intervolutions/ivolt/carousel or auto.js. Added in v0.3.

    A slideshow that works without JavaScriptfixtures/carousel/basic.htmlOpen alone — A slideshow that works without JavaScript
    <section class="iv-carousel" data-iv-component="carousel" aria-roledescription="carousel" aria-label="Sample work. The four projects below are made up for this demo.">
  <div class="iv-carousel__viewport">
    <ul class="iv-carousel__track">
      <li class="iv-carousel__slide" id="cw-aurora">
        <figure class="iv-carousel__media">
          <svg role="img" aria-label="Abstract artwork: a green glow rising behind two long arcs on a dark green field." viewBox="0 0 1600 900" preserveAspectRatio="xMidYMid slice">
            <defs>
              <linearGradient id="cw-a1" x1="0" y1="0" x2="1600" y2="900" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#094D63"/><stop offset=".6" stop-color="#04070F"/><stop offset="1" stop-color="#0C1330"/>
              </linearGradient>
              <radialGradient id="cw-a2" cx="420" cy="620" r="700" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#73DFFF" stop-opacity=".65"/><stop offset="1" stop-color="#73DFFF" stop-opacity="0"/>
              </radialGradient>
            </defs>
            <rect width="1600" height="900" fill="url(#cw-a1)"/>
            <rect width="1600" height="900" fill="url(#cw-a2)"/>
            <circle cx="1230" cy="240" r="190" fill="#2266D8" fill-opacity=".38"/>
            <path d="M-60 560C320 300 660 760 1660 340" fill="none" stroke="#66B1FF" stroke-opacity=".55" stroke-width="4"/>
            <path d="M-60 660C360 430 720 880 1660 460" fill="none" stroke="#73DFFF" stroke-opacity=".3" stroke-width="10"/>
          </svg>
        </figure>
        <span class="iv-carousel__scrim" aria-hidden="true"></span>
        <div class="iv-carousel__caption">
          <span class="iv-badge iv-badge--primary iv-badge--solid">Case study</span>
          <h3>Aurora energy dashboard</h3>
          <p>A control room for a fictional grid operator, built with iVOLT tokens, layout primitives and no runtime dependencies.</p>
        </div>
      </li>
      <li class="iv-carousel__slide" id="cw-harbour">
        <figure class="iv-carousel__media">
          <svg role="img" aria-label="Abstract artwork: blue bands crossing a dark field with a soft green halo." viewBox="0 0 1600 900" preserveAspectRatio="xMidYMid slice">
            <defs>
              <linearGradient id="cw-b1" x1="1600" y1="0" x2="0" y2="900" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#0C1330"/><stop offset=".5" stop-color="#04070F"/><stop offset="1" stop-color="#171A45"/>
              </linearGradient>
              <radialGradient id="cw-b2" cx="1180" cy="300" r="640" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#2266D8" stop-opacity=".75"/><stop offset="1" stop-color="#2266D8" stop-opacity="0"/>
              </radialGradient>
            </defs>
            <rect width="1600" height="900" fill="url(#cw-b1)"/>
            <rect width="1600" height="900" fill="url(#cw-b2)"/>
            <path d="M0 620 1600 380 1600 520 0 760Z" fill="#8B95FF" fill-opacity=".2"/>
            <path d="M0 700 1600 460 1600 500 0 740Z" fill="#66B1FF" fill-opacity=".35"/>
            <circle cx="360" cy="250" r="140" fill="#8B95FF" fill-opacity=".3"/>
          </svg>
        </figure>
        <span class="iv-carousel__scrim" aria-hidden="true"></span>
        <div class="iv-carousel__caption">
          <span class="iv-badge iv-badge--primary iv-badge--solid">Field report</span>
          <h3>Harbour logistics board</h3>
          <p>Sample data only: berths, tides and crane slots on one dense table that still reads on a phone.</p>
        </div>
      </li>
      <li class="iv-carousel__slide" id="cw-kit">
        <figure class="iv-carousel__media">
          <svg role="img" aria-label="Abstract artwork: concentric green rings over a deep carbon background." viewBox="0 0 1600 900" preserveAspectRatio="xMidYMid slice">
            <defs>
              <linearGradient id="cw-c1" x1="0" y1="900" x2="1600" y2="0" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#04070F"/><stop offset="1" stop-color="#172F7A"/>
              </linearGradient>
            </defs>
            <rect width="1600" height="900" fill="url(#cw-c1)"/>
            <circle cx="820" cy="470" r="420" fill="none" stroke="#66B1FF" stroke-opacity=".5" stroke-width="3"/>
            <circle cx="820" cy="470" r="300" fill="none" stroke="#66B1FF" stroke-opacity=".35" stroke-width="6"/>
            <circle cx="820" cy="470" r="170" fill="#66B1FF" fill-opacity=".22"/>
            <path d="M-40 840C420 700 560 220 1640 120" fill="none" stroke="#66B1FF" stroke-opacity=".45" stroke-width="4"/>
          </svg>
        </figure>
        <span class="iv-carousel__scrim" aria-hidden="true"></span>
        <div class="iv-carousel__caption">
          <span class="iv-badge iv-badge--primary iv-badge--solid">Product</span>
          <h3>Voltage design kit</h3>
          <p>Every surface in this made-up kit is a token: change one value and the whole slideshow follows.</p>
        </div>
      </li>
      <li class="iv-carousel__slide" id="cw-tidal">
        <figure class="iv-carousel__media">
          <svg role="img" aria-label="Abstract artwork: a wide green wave breaking across a dark blue horizon." viewBox="0 0 1600 900" preserveAspectRatio="xMidYMid slice">
            <defs>
              <linearGradient id="cw-d1" x1="0" y1="0" x2="0" y2="900" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#0C1330"/><stop offset="1" stop-color="#0C1330"/>
              </linearGradient>
              <radialGradient id="cw-d2" cx="760" cy="880" r="760" gradientUnits="userSpaceOnUse">
                <stop offset="0" stop-color="#8FE3FF" stop-opacity=".55"/><stop offset="1" stop-color="#8FE3FF" stop-opacity="0"/>
              </radialGradient>
            </defs>
            <rect width="1600" height="900" fill="url(#cw-d1)"/>
            <path d="M-40 500C400 340 700 700 1640 400L1640 900-40 900Z" fill="#2266D8" fill-opacity=".45"/>
            <rect width="1600" height="900" fill="url(#cw-d2)"/>
            <circle cx="1320" cy="180" r="110" fill="#FBBF24" fill-opacity=".3"/>
          </svg>
        </figure>
        <span class="iv-carousel__scrim" aria-hidden="true"></span>
        <div class="iv-carousel__caption">
          <span class="iv-badge iv-badge--primary iv-badge--solid">Research</span>
          <h3>Tidal turbine telemetry</h3>
          <p>Invented readings from an imaginary estuary, plotted with nothing but CSS gradients and inline SVG.</p>
        </div>
      </li>
    </ul>
  </div>
  <nav class="iv-carousel__dots" aria-label="Slides">
    <a href="#cw-aurora"><span class="iv-u-sr-only">Slide 1: Aurora energy dashboard</span></a>
    <a href="#cw-harbour"><span class="iv-u-sr-only">Slide 2: Harbour logistics board</span></a>
    <a href="#cw-kit"><span class="iv-u-sr-only">Slide 3: Voltage design kit</span></a>
    <a href="#cw-tidal"><span class="iv-u-sr-only">Slide 4: Tidal turbine telemetry</span></a>
  </nav>
  <div class="iv-carousel__controls">
    <button class="iv-button iv-carousel__prev" type="button" aria-label="Previous slide" hidden>&#8592;</button>
    <button class="iv-button iv-carousel__next" type="button" aria-label="Next slide" hidden>&#8594;</button>
  </div>
</section>

    Cinema effect with autoplay

    data-iv-effect="cinema" crossfades the slides and adds a slow zoom on the active media while the caption rises. With data-iv-autoplay the component adds a large counter and a progress bar that fills over the interval; the play/pause button exposes its state with aria-pressed.

    Thumbnails

    Give the dots the iv-carousel__dots--thumbs class and put a small image in each anchor: they become thumbnail tabs. This example uses the fade effect.

    With photographs

    Real images from Unsplash (credited in the captions), the cinema effect and a seven-second autoplay. The images live with the documentation, not in the package.

    Options

    OptionAttributeDefaultEffect
    effectdata-iv-effectslideslide, fade or cinema.
    autoplaydata-iv-autoplay0Milliseconds between slides; 0 disables autoplay. Never starts under reduced motion.
    loopdata-iv-looptrueWrap around at both ends.
    pauseOnHoverdata-iv-pause-on-hovertruePause autoplay while the pointer is over the carousel.
    swipedata-iv-swipetruePointer drag changes the slide (40 px threshold).
    durationdata-iv-duration600Transition length in milliseconds.
    pauseText, playTextdata-iv-pause-text, data-iv-play-textPause, PlayLabels of the toggle button.

    Methods and events

    next(), prev(), goTo(index), play(), pause(), destroy(); read index, count, isPlaying and slides. Events on the root element: iv:change (cancelable, detail.index, previousIndex, reason) then iv:changed; iv:play and iv:pause with a reason.

    Keyboard, gestures and assistive technology

    Left and Right move between slides from the tabs or from the viewport, Home and End jump, Enter and Space activate a tab. Dragging with a pointer changes the slide. The markup follows the tabbed carousel pattern: each slide is a panel labelled "n of N", non-visible slides are inert in the fade and cinema effects, and the viewport is a live region only while autoplay is paused, so the reader is not interrupted by every change.

    Without JavaScript

    The track scrolls horizontally and snaps to each slide, the dots are anchor links that scroll the matching slide into view, and the buttons stay hidden. Captions sit on a gradient scrim so the text stays readable on any media.

    Common mistakes

    • Media without alt text or an aria-label: every slide needs a name.
    • Autoplay on a carousel with links and forms inside: readers lose their place. Prefer manual navigation or a long interval.
    • Using the carousel for essential content: nothing important should only exist on slide four.

    Class index

    Parts and modifiers of this family that the examples above do not show. The full list per stylesheet lives in the reference.

    ClassWhat it does
    iv-carousel__scrimGradient laid over the slide so a caption stays legible on any photograph; generated by init when the carousel has captions.