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>

JavaScript Reference

Constructor

Extends ShadowComponent

new PhotoViewer()

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

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