popupable

Features

• No dependencies
• Animates open from the element's original position
• Works with mouse, touch, and keyboard
• Gallery groups with swipe, scroll, keyboard, and button navigation
• Supports both images and videos
• Thumbnail strip and image counter
• Pinch-to-zoom on touch, with optional click/tap-to-zoom support
• Load a hi-res image on open
• Checkerboard background for transparent images
• Attribute inheritance - set options on a parent to apply to all children
• Customizable via CSS variables

Basic Usage

Add data-popupable to any image. Click the image to open it.

<img src="image.webp" data-popupable>

Title & Description

Add data-popupable-title and data-popupable-description to show text alongside the opened image.

<img src="image.webp" data-popupable
     data-popupable-title="Mountain Lake"
     data-popupable-description="A serene lake nestled in the mountains">

Alternate Image Source

Use data-popupable-src to specify a different image source for the popup. This can be used to display a completely different image, or to load a higher resolution version.

<img src="thumbnail.webp" data-popupable data-popupable-src="full-res.webp">

Animation Styles

Use data-popupable-anim to control the open and close animation. You can also register your own custom animations - see Custom animation styles in the README.

<img src="image.webp" data-popupable data-popupable-anim="expand">
<img src="image.webp" data-popupable data-popupable-anim="pop">
<img src="image.webp" data-popupable data-popupable-anim="line">
<img src="image.webp" data-popupable data-popupable-anim="float">

Use the toggle below to change the animation style on all images on this page.

Zoom

All images support pinch-to-zoom on touch devices. Add data-popupable-zoomable to also enable click/tap-to-zoom. After entering the zoomed state, scroll to zoom and drag to pan. Click again to exit.

<img src="image.webp" data-popupable data-popupable-zoomable>

Transparent Images

Add data-popupable-transparent to show a checkerboard pattern behind transparent areas.

<img src="icon.png" data-popupable data-popupable-transparent>

Aspect Ratio

By default, the popup size is based on the image's natural dimensions. Add data-popupable-maintain-aspect to use the element's rendered aspect ratio instead. Toggle the checkbox to see the difference.

<img src="image.webp" data-popupable data-popupable-maintain-aspect>

Gallery Groups

Group images into a gallery with data-popupable-group. Navigate with arrow buttons, swipe, scroll wheel, or keyboard arrows.

<img src="photo1.webp" data-popupable data-popupable-group="gallery">
<img src="photo2.webp" data-popupable data-popupable-group="gallery">

Counter

Add data-popupable-counter to show the current position within the group.

<img src="photo1.webp" data-popupable data-popupable-group="gallery" data-popupable-counter>
<img src="photo2.webp" data-popupable data-popupable-group="gallery" data-popupable-counter>

Thumbnails

Add data-popupable-thumbnails to show a strip of thumbnails for quick navigation.

<img src="photo1.webp" data-popupable data-popupable-group="gallery" data-popupable-thumbnails>
<img src="photo2.webp" data-popupable data-popupable-group="gallery" data-popupable-thumbnails>

Videos

Videos work the same way as images. popupable detects videos automatically from <video> tags or video file extensions.

<video src="clip.mp4" data-popupable></video>
<video src="clip.mp4" data-popupable data-popupable-attr="controls=false,loop,autoplay"></video>
<video src="clip.mp4" data-popupable data-popupable-attr="playbackRate=4"></video>
<video src="clip.mp4" data-popupable data-popupable-zoomable></video>

A few extras specific to videos:

data-popupable-attr

Sets properties on the underlying <video> element (e.g. controls=false,loop,autoplay,playbackRate=2). Comma-separated name or name=value pairs.

data-popupable-poster

Overrides the poster image used by the popup and thumbnail strip. <video> tags fall back to their native poster attribute, so this is only needed when the source isn't a <video> or when you want a different poster for the popup than the page.

data-popupable-type="video"

Forces popupable to treat any element as a video when the URL extension doesn't reveal the format. data-popupable-type="image" does the opposite.

Inheritance

All data-popupable-* attributes are inherited from parent elements. Set them once on a container instead of repeating on every image. Set an attribute to "false" to opt out on individual images. The last image below opens without thumbnails.

<div data-popupable-group="gallery" data-popupable-counter data-popupable-thumbnails>
  <img src="image.webp" data-popupable>
  <img src="image.webp" data-popupable>
  <img src="image.webp" data-popupable>
  <img src="image.webp" data-popupable data-popupable-thumbnails="false">
</div>

Combining Features

The counter, thumbnails, titles, and descriptions can all be combined together.

<div data-popupable-group="gallery" data-popupable-counter data-popupable-thumbnails>
  <img src="photo1.webp" data-popupable data-popupable-title="..." data-popupable-description="...">
  <img src="photo2.webp" data-popupable data-popupable-title="..." data-popupable-description="...">
</div>

Reordering UI Components

Use data-popupable-order to reorder the UI elements. The available tokens are counter, image, content, and thumbnails. Elements placed before image appear above it, and those after appear below.

<div data-popupable-group="gallery" data-popupable-counter data-popupable-thumbnails
     data-popupable-order="content, image, counter, thumbnails">
  <img src="photo1.webp" data-popupable data-popupable-title="..." data-popupable-description="...">
  <img src="photo2.webp" data-popupable data-popupable-title="..." data-popupable-description="...">
</div>

Unique IDs

Set a value on data-popupable to give the popup a CSS id. In a gallery, the id updates as you navigate, so each image can have its own backdrop colour.

<div data-popupable-group="unique-ids" data-popupable-counter>
  <img src="image.webp" data-popupable="unique-ids-1">
  <img src="image.webp" data-popupable="unique-ids-2">
</div>

<style>
  #unique-ids-1.popupable-active { background: #AE8FDBBB; }
  #unique-ids-2.popupable-active { background: #BE5203BB; }
</style>

Customization Variables

Fine-tune the popup appearance with CSS variables.

<style>
  :root {
    --popupable-background: #000B;     /* Backdrop color */
    --popupable-blur: 6px;             /* Backdrop blur amount */
    --popupable-ui-background: #0008;  /* Header, footer, and button background */
    --popupable-text-color: #fff;      /* Text and icon color */
    --popupable-screen-padding: 40px;  /* Gap between image and viewport edge */
    --popupable-open-duration: .25s;   /* Open/close transition duration */
    --popupable-open-easing: ease;     /* Open/close transition easing */
    --popupable-switch-duration: .25s; /* Gallery navigation transition duration */
    --popupable-switch-easing: ease;   /* Gallery navigation transition easing */
  }
</style>