Skip to main content

Image viewer

Image viewer 2 is an accessible, configurable component providing options for showing an image slideshow and/or a lightbox viewer with navigation between images.

Örebro Castle
Karlslund Manor House
Highland cattle at Oset outside Örebro

Features include

  • Buttons for displaying the previous and next slides.
  • Button for stopping and restarting rotation.
  • Keyboard navigation support.
  • Aria-live announcement for image changes.
  • Optional automatic rotation, always disabled for users who prefers reduced motion.
  • Optional download button in lightbox.
  • Optional placement of slideshow buttons.

Use attribute data-zoom on one or more links inside the element being initialized from script. The lightbox opens with navigation arrows to switch between images. The link href:s should point to a large version of the image being shown.

  • Dry grass in sunlight

  • Bright green fern leaves

  • Two little snails on a green leaf

  • A close-up of a dandelion

<div id="example-imageviewer2-1" class="example-imageviewer2-images">
   <ul
      class="env-list env-cardholder-grid"
      style="--env-cardholder-grid-column-width: 10em;"
   >
      <li>
         <button
            type="button"
            aria-label="Zoom image: Dry grass in sunlight"
            data-href="/placeholders/originals/03.webp"
            data-zoom
         >
            <img
               loading="lazy"
               src="/placeholders/225x100/03.webp"
               data-figcaption="A strand of grass catching the warm glow of the sun"
               alt="Dry grass in sunlight"
            />
         </button>
         <p class="env-text-caption-01">Dry grass in sunlight</p>
      </li>
      <li>
         <button
            type="button"
            aria-label="Zoom image: Bright green fern leaves"
            data-href="/placeholders/originals/04.webp"
            data-zoom
         >
            <img
               loading="lazy"
               src="/placeholders/225x100/04.webp"
               alt="Bright green fern leaves"
               data-figcaption="Bright green fern fronds filling the frame in soft light"
            />
         </button>
         <p class="env-text-caption-01">Bright green fern leaves</p>
      </li>
      <li>
         <button
            type="button"
            aria-label="Zoom image: Two little snails on a green leaf"
            data-href="/placeholders/originals/08.webp"
            data-zoom
         >
            <img
               loading="lazy"
               src="/placeholders/225x100/08.webp"
               data-figcaption="Two little snails hanging out on a green leaf in the shade"
               alt="Two little snails on a green leaf"
            />
         </button>
         <p class="env-text-caption-01">Two little snails on a green leaf</p>
      </li>
      <li>
         <button
            type="button"
            aria-label="Zoom image: A close-up of a dandelion"
            data-href="/placeholders/originals/09.webp"
            data-zoom
         >
            <img
               loading="lazy"
               src="/placeholders/225x100/09.webp"
               data-figcaption="A close-up of a dandelion ready to spread its seeds on a sunny day"
               alt="A close-up of a dandelion"
            />
         </button>
         <p class="env-text-caption-01">A close-up of a dandelion</p>
      </li>
   </ul>
</div>

envision.imageViewer2(document.querySelector('#example-imageviewer2-1'));

Slideshow

Örebro Castle
Karlslund Manor House
Highland cattle at Oset outside Örebro 
<section
   id="example-imageviewer2-2"
   class="env-p-around--medium"
   aria-label="Photos from Örebro"
>
   <figure data-href="/placeholders/originals/10.webp" data-zoom>
      <img src="/placeholders/900x400/10.webp" alt="" />
      <figcaption class="env-image-viewer-2__viewer__caption">
         Örebro Castle
      </figcaption>
   </figure>
   <figure data-href="/placeholders/originals/05.webp" data-zoom>
      <img src="/placeholders/900x400/05.webp" alt="" />
      <figcaption class="env-image-viewer-2__viewer__caption">
         Karlslund Manor House
      </figcaption>
   </figure>
   <figure data-href="/placeholders/originals/02.webp" data-zoom>
      <img src="/placeholders/900x400/02.webp" alt="" />
      <figcaption class="env-image-viewer-2__viewer__caption">
         Highland cattle at Oset outside Örebro
      </figcaption>
   </figure>
</section>

envision.imageViewer2(document.querySelector('#example-imageviewer2-2'), {
   slides: {
      auto: 3000,
      playing: false,
      overlay: false,
      buttons: {
         type: 'secondary',
         size: 'slim',
      },
   },
});

Slideshow markup

  • All immediate child elements of the container will be included in slideshow.
  • The container used for initialization should have an aria-label attribute.
<section aria-label="Slideshow label">
   <img src="example-1.webp" alt="Image description" />
   <img src="example-2.webp" alt="Image description" />
</section>

Zoom

Add attribute data-zoom to activate zoom/lightbox. Add URL to larger images in data-href.

<section aria-label="Slideshow label">
   <img
      src="example-1.webp"
      alt="Image description"
      data-href="example-1-large.webp"
      data-zoom
   />
   <img
      src="example-2.webp"
      alt="Image description"
      data-href="example-2-large.webp"
      data-zoom
   />
</section>

Optionally wrap the image in a link pointing to the larger image. The href attribute will be used for zoom and data-zoom should be added to the link, not the image.

<section aria-label="Slideshow label">
   <a href="example-1-large.webp" data-zoom>
      <img src="example-1.webp" alt="Image description" />
   </a>
   <a href="example-2-large.webp" data-zoom>
      <img src="example-2.webp" alt="Image description" />
   </a>
</section>

Caption

Wrap images in a figure element and include a figcaption with the class env-image-viewer-2__viewer__caption to provide descriptive text.

Captions can be combined with zoom functionality in two ways:

  • By adding data-href and data-zoom attributes directly on the
    element.
  • By using an <a> element with href and data-zoom, wrapping the image and caption.
<section aria-label="Slideshow label">
   <figure data-href="example-1-large.webp" data-zoom>
      <img src="example-1.webp" alt="" />
      <figcaption class="env-image-viewer-2__viewer__caption">
         Image 1 caption
      </figcaption>
   </figure>
   <a href="example-2-large.webp" data-zoom>
      <img src="example-2.webp" alt="" />
      <div class="env-image-viewer-2__viewer__caption">Image 2 caption</div>
   </a>
</section>

Zoom and caption 2025.09.2

A <figcaption> placed inside a data-zoom link or <figure> will automatically be displayed in the lightbox.

Alternatively, use the data-figcaption attribute on an <img> to show caption text in the lightbox without rendering it in the slideshow.

<section aria-label="Slideshow label">
   <figure data-href="example-1-large.webp" data-zoom>
      <img src="example-1.webp" alt="" />
      <figcaption class="env-image-viewer-2__viewer__caption">
         Image 1 caption
      </figcaption>
   </figure>
   <a href="example-2-large.webp" data-zoom>
      <img src="example-2.webp" alt="" data-figcaption="Image 2 caption" />
   </a>
</section>

Options

// Default options
{
   slides: false,
   buttons: {
      download: true,
      showText: false,
   },
   i18n: 'sv',
}

// Default slides options if set to true
{
   auto: 0,
   speed: 300,
   draggable: true,
   playing: false,
   overlay: true,
   buttons: {
      type: null,
      ghost: false,
      size: null,
   },
},

  • buttons { download, showText }

    • Lightbox button options. Show/hide download button. Visible text in close/download buttons.
    • Default values: { download: true, showText: false }

  • i18n ‘sv’ | ‘en’ | ‘no’ | { language keys }

    • Translation of buttons aria-label and aria-roledescription. Use predefined strings (swedish, english or norwegian) or write your own translation. Default is ‘sv’.
    • Available language keys: roledescription, prev, next, pause, play, slideshow, zoom, largeImage, close, download, image, of

  • slides boolean | { options object }

    • Initialize a slideshow with default or custom options
    • Default value: false

Slides options object

  • auto number

    • Auto rotation possible, play button visible. Number is interval in ms.
    • Default value: 0 (auto rotation not available)

  • speed number

    • Slide speed in ms.
    • Default value: 300

  • draggable boolean

    • Slides listen to mouse drag events in addition to touch events.
    • Default value: true

  • playing boolean

    • If auto is set to > 0, this will start auto rotation automatically.
    • Default value: false

  • overlay boolean

    • Control buttons and caption should overlay the slides.
    • Default value: true

  • buttons { size, type, ghost }

    • Control button appearance.
    • Allowed value for type: Any Element color name in lowercase.
    • Allowed value for size: Any Button size name in lowercase.
    • Allowed value for ghost: true/false

API functions

Instances of Image viewer 2 may be controlled by the methods described below.

envision.imageViewer2('#image-viewer').then(function (imageViewers) {
   imageViewers[0].slider.pause();
   imageViewers[0].lightbox.show(1);
});

Slider

  • slider.pause()

    • Pause slider automatic rotation.

  • slider.play()

    • Start slider automatic rotation if available.

  • slider.next()

    • Show next image.

  • slider.prev()

    • Show previous image.

  • slider.goTo(index, speed)

    • Set slider to image at position index. Use speed to control how fast image is shown.

  • slider.getPos()

    • Get index for current image.

  • lightbox.show(index)

    • Show lightbox starting at index. Defaults to index 0.

  • lightbox.close()

    • Close the lightbox.

Legacy documentation

Image Viewer 2 is a replacement for the following, which are deprecated since 2023.07.1:

Envision documentation