Image viewer 2

Since 2023.07.01

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

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.

Lightbox

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.

<div
   id="example-imageviewer2-1"
   class="example-imageviewer2-images env-text env-flex env-flex--justify-content-around"
>
   <a href="/placeholders/originals/03.webp" data-zoom>
      <img loading="lazy" src="/placeholders/225x100/03.webp" alt="Grass" />
   </a>
   <a href="/placeholders/originals/04.webp" data-zoom>
      <img loading="lazy" src="/placeholders/225x100/04.webp" alt="Fern" />
   </a>
   <a href="/placeholders/originals/08.webp" data-zoom>
      <img loading="lazy" src="/placeholders/225x100/08.webp" alt="Snail" />
   </a>
   <a href="/placeholders/originals/09.webp" data-zoom>
      <img loading="lazy" src="/placeholders/225x100/09.webp" alt="Dandelion" />
   </a>
</div>

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

Slideshow

<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 the images in a figure tag and add a figcaption with class env-image-viewer-2__viewer__caption.

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

Zoom and caption

Combine zoom and captions using data attributes or links:

<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>

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' | { language keys }
- Translation of buttons aria-label and aria-roledescription. Use predefined strings for swedish or english or write your own translation. Default is 'sv' or 'en' depending on HTML lang attribute.
- 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

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: