PhotoViewer

Basic Usage

The k-photo-viewer component displays images with fullscreen viewing capabilities. Click on any image to open it in fullscreen mode.

<k-photo-viewer
  src="../media/civic.jpg"
  alt="Honda Civic Type R"
>
  <p>Honda Civic Type R - Track-focused hot hatch</p>
</k-photo-viewer>

Gallery Navigation

When multiple PhotoViewer components are siblings, you can navigate between them using the arrow buttons in fullscreen mode or keyboard arrow keys.

<div class="gallery">
  <k-photo-viewer src="../media/civic.jpg" alt="Honda Civic Type R">
    <h6>Honda Civic Type R</h6>
  </k-photo-viewer>
  <k-photo-viewer src="../media/corvette.jpg" alt="Chevrolet Corvette C8">
    <h6>Chevrolet Corvette C8</h6>
  </k-photo-viewer>
  <k-photo-viewer src="../media/evo.jpg" alt="Mitsubishi Lancer Evolution">
    <h6>Mitsubishi Lancer Evolution</h6>
  </k-photo-viewer>
</div>

Global Navigation

With the global attribute, PhotoViewers can navigate between all instances on the page, not just siblings.

<k-photo-viewer
  src="../media/gtr.jpg"
  alt="Nissan GT-R"
  global
>
  <h6>Nissan GT-R (Global Navigation)</h6>
</k-photo-viewer>

Custom Controls

Customize the fullscreen controls using slots and disable keyboard controls if needed.

<k-photo-viewer
  src="../media/nsx.jpg"
  alt="Honda NSX"
  keyboard-controls="false"
>
  <span slot="close">✕</span>
  <span slot="prev">◀</span>
  <span slot="next">▶</span>
  <h6>Honda NSX</h6>
  <p>Custom controls, keyboard disabled</p>
</k-photo-viewer>
<k-photo-viewer
  src="../media/evo.jpg"
  alt="Mitsubishi Lancer Evolution"
  keyboard-controls="false"
>
  <span slot="close">✕</span>
  <span slot="prev">◀</span>
  <span slot="next">▶</span>
  <h6>Mitsubishi Lancer Evolution</h6>
  <p>Custom controls, keyboard disabled</p>
</k-photo-viewer>

Captions

Use different captions for thumbnail view and fullscreen view using slots.

<k-photo-viewer
  src="../media/corvette.jpg"
  alt="Chevrolet Corvette C8"
>
  <!-- Default caption (thumbnail view) -->
  <h6>Corvette C8</h6>
  
  <!-- Fullscreen caption -->
  <div slot="fullscreen-caption">
    <h4>2020 Chevrolet Corvette C8 Stingray</h4>
    <p>The first mid-engine Corvette featuring a 6.2L V8 engine</p>
  </div>
</k-photo-viewer>

Programmatic Gallery

Use the static PhotoViewer.open(content, openIndex, options) method to launch a fullscreen gallery popup directly from JavaScript, without needing any k-photo-viewer thumbnails in the page. content is an array of { src, caption } objects, where caption can be an HTML string or a lit html template. openIndex (optional, default 0) is the index of the photo to open first, and navigation wraps within the array.

<button id="galleryBtn">Open Gallery</button>
<script type="module">
  import PhotoViewer from '/src/components/PhotoViewer.js';
  import { html } from '/src/lit-all.min.js';

  document.getElementById('galleryBtn').addEventListener('click', () => {
    PhotoViewer.open([
      { src: '../media/civic.jpg', caption: '<h6>Honda Civic Type R</h6>' },
      { src: '../media/corvette.jpg', caption: html`<h6>Chevrolet Corvette C8</h6>` },
      { src: '../media/evo.jpg', caption: '<h6>Mitsubishi Lancer Evolution</h6>' }
    ], 1);
  });
</script>

JavaScript Reference

Constructor

Extends ShadowComponent

new PhotoViewer()

Creates a new PhotoViewer instance. Configuration is done through attributes or properties.

Static Methods

PhotoViewer.open(content: Array<{ src, caption }>, openIndex?: number, options?: object): PhotoViewer

Opens a fullscreen gallery popup without needing any k-photo-viewer elements on the page. Creates a hidden, isolated set of PhotoViewers, opens the one at openIndex, and removes them all from the DOM once the gallery is fully closed.

• content: Array of { src, caption, alt } objects. src is the image URL. caption is optional and may be an HTML string or a lit html template result; it's used as both the default caption and the fullscreen caption. alt is optional alt text for the image.
• openIndex: Index within content to open first. Defaults to 0.
• options.keyboardControls: Whether keyboard controls (Escape, Arrow Left/Right) are enabled for the popup. Defaults to true.
• options.onClose: Callback invoked after the gallery is fully closed and removed from the DOM.

Returns the PhotoViewer instance that was opened.

Requirements

• ShadowComponent
• Icon

Properties

src: string

The URL of the image to display. Syncs with the src attribute.

alt: string

Alternative text for the image. Syncs with the alt attribute.

fullscreen: boolean

Whether the photo viewer is currently in fullscreen mode. Syncs with the fullscreen attribute.

keyboardControls: boolean

Whether keyboard controls are enabled (default: true). When enabled: Enter opens fullscreen, ESC closes, arrow keys navigate. Syncs with the keyboard-controls attribute.

global: boolean

Whether navigation should include all PhotoViewers on the page (true) or just siblings (false, default). Syncs with the global attribute.

Methods

open(): void

Opens the photo viewer in fullscreen mode.

close(): void

Closes the fullscreen mode.

toggle(): void

Toggles between fullscreen and normal mode.

Events

fullscreenchange

Fired when the fullscreen state changes. Event detail contains { fullscreen: boolean }.

fullscreen

Fired when entering fullscreen mode.

fullscreenclose

Fired when exiting fullscreen mode.

Slots

default

Caption content displayed below the thumbnail image.

fullscreen-caption

Caption content displayed in fullscreen mode. If not provided, the default slot content is cloned.

close

Custom close button content. Defaults to a close icon.

prev

Custom previous button content. Defaults to a chevron-left icon.

next

Custom next button content. Defaults to a chevron-right icon.

Keyboard Controls

When keyboard-controls is enabled (default):

• Enter: Open fullscreen when focused on thumbnail
• Escape: Close fullscreen
• Arrow Left: Navigate to previous photo
• Arrow Right: Navigate to next photo

Navigation Behavior

Navigation between photos works as follows:

• Sibling mode (default): Navigate only between PhotoViewer components that are direct siblings
• Global mode: Navigate between all PhotoViewer components on the page
• Wrap-around: Navigation wraps from last to first photo and vice versa
• Auto-hide: Navigation buttons are hidden when only one photo is available