Skip to content

Lightbox

<quiet-lightbox> stable since 6.6

Opens linked images, videos, embeds, and inline content in a full-screen viewer that users can swipe or step through. Use a lightbox when thumbnails on the page should expand in place without navigating away.

Wrap one or more linked images in a lightbox and each link will become an item. The link's href points to the full-size image, so the gallery will still work as regular links if JavaScript hasn't loaded. Thumbnails are optional, as any link or button can open a lightbox.

An orange kitten meows outdoors A long-haired cat sits in a field of orange flowers A kitten sleeps peacefully on the floor A gray and white cat sleeps on a blanket with evening lights in the background
<quiet-lightbox id="lightbox__overview" label="Cat photos" loop with-thumbnails>
  <a href="https://images.unsplash.com/photo-1628612380382-e6204e135307?q=80&w=2000&auto=format&fit=crop" data-caption="Biscuit, announcing that it's breakfast time">
    <img src="https://images.unsplash.com/photo-1628612380382-e6204e135307?q=80&w=500&auto=format&fit=crop" alt="An orange kitten meows outdoors">
  </a>
  <a href="https://images.unsplash.com/photo-1589538923929-76e12402048b?q=80&w=2000&auto=format&fit=crop" data-caption="Willow, out among the wildflowers">
    <img src="https://images.unsplash.com/photo-1589538923929-76e12402048b?q=80&w=500&auto=format&fit=crop" alt="A long-haired cat sits in a field of orange flowers">
  </a>
  <a href="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=2000&auto=format&fit=crop" data-caption="Mochi, three naps into a four-nap day">
    <img src="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=500&auto=format&fit=crop" alt="A kitten sleeps peacefully on the floor">
  </a>
  <a href="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=2000&auto=format&fit=crop" data-caption="Socks, tucked in for the evening">
    <img src="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=500&auto=format&fit=crop" alt="A gray and white cat sleeps on a blanket with evening lights in the background">
  </a>
</quiet-lightbox>

<style>
  #lightbox__overview {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(140px, 1fr));
    gap: 0.5rem;

    a {
      display: block;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }
</style>

The lightbox is styled with display: contents so you can apply flex and grid layouts to the containing element without the wrapper interfering. In this example, the grid is applied directly to the lightbox.

Examples Jump to heading

Providing items Jump to heading

Any <a href> inside the lightbox that contains an <img> will become an item. The link's href is used for the full-size image and the <img> is used as its thumbnail. Links without an image are ignored unless you give them a data-lightbox type. If a linked image shouldn't be part of the gallery, such as an avatar, add data-lightbox="ignore" to the link.

<quiet-lightbox>
  <!-- An item -->
  <a href="/photos/whiskers-large.jpg">
    <img src="/photos/whiskers-thumb.jpg" alt="Captain Whiskers surveys the yard">
  </a>

  <!-- Not an item -->
  <a href="/photographer" data-lightbox="ignore">
    <img src="/avatars/photographer.jpg" alt="">
  </a>
</quiet-lightbox>

Thumbnails aren't required. Add data-lightbox="image" to any link, including a text link, to make it an item. Items can also be hidden, which is useful when you want a button to open a gallery that isn't shown on the page. See opening and closing lightboxes for more details.

By default, the full-size image uses the thumbnail's alt text. If there's no thumbnail, or if the full-size image needs a different description, use the data-alt attribute to describe it for assistive devices.

Meowy McGee has been caught napping on the good pillow again.

See the evidence
<quiet-lightbox id="lightbox__no-thumbnails">
  <p>
    Meowy McGee has been <a href="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=2000&auto=format&fit=crop" data-lightbox="image" data-caption="Caught in the act" data-alt="An orange cat sleeps at the edge of a bed">caught napping on the good pillow</a> again.
  </p>

  <quiet-button data-lightbox="open lightbox__no-thumbnails 1">
    <quiet-icon slot="start" name="photo"></quiet-icon>
    See the evidence
  </quiet-button>

  <a href="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=2000&auto=format&fit=crop" data-lightbox="image" data-caption="Exhibit B" data-alt="A kitten sleeps on the floor" hidden>Exhibit B</a>
</quiet-lightbox>

<style>
  #lightbox__no-thumbnails p {
    margin-block-start: 0;
  }
</style>

If you serve images in multiple sizes, you can add data-srcset and data-sizes to the link. These work the same way as srcset and sizes on an <img>.

<a
  href="/photos/whiskers-2000.jpg"
  data-srcset="/photos/whiskers-1000.jpg 1000w, /photos/whiskers-2000.jpg 2000w"
  data-sizes="100vw"
>
  <img src="/photos/whiskers-thumb.jpg" alt="Captain Whiskers surveys the yard">
</a>

Until the full-size image loads, the zoom animation uses the thumbnail's aspect ratio. If your thumbnails are cropped to a different aspect ratio, add data-width and data-height to the link with the full-size image's dimensions in pixels for a smoother animation.

Data attributes Jump to heading

Items are configured with data-* attributes on their links. Each one is covered in the examples below, but here they are in one place.

Attribute Applies to Description
data-lightbox All items The item's type: image, video, iframe, or html. Links that contain an <img> are images by default. Use ignore to exclude a link.
data-caption All items A plain text caption. For HTML captions, use a <figure> with a <figcaption> instead.
data-alt All items A description for assistive devices. Defaults to the thumbnail's alt text.
data-thumbnail All items The URL of the image to show in the thumbnail strip. Defaults to the image inside the link.
data-srcset Images Image sources in multiple sizes, the same as srcset on an <img>.
data-sizes Images The sizes to use with data-srcset, the same as sizes on an <img>.
data-width Images, videos The full-size media's width in pixels. Use with data-height when the thumbnail has a different aspect ratio.
data-height Images, videos The full-size media's height in pixels.
data-aspect-ratio Videos, iframes The aspect ratio to show the item at, e.g. 9 / 16. Defaults to 16 / 9.
data-poster Videos The URL of the video's poster image. Defaults to the thumbnail.
data-autoplay Videos Starts playing the video as soon as it's shown.

Adding captions Jump to heading

Use the data-caption attribute to add a plain text caption to any item.

<a href="/photos/whiskers-large.jpg" data-caption="Captain Whiskers surveys the yard">
  <img src="/photos/whiskers-thumb.jpg" alt="A tabby cat sits on a fence">
</a>

To use HTML in a caption, place the link inside a <figure> with a <figcaption> and its content will be used instead. Links and formatting will be preserved.

A gray and white kitten looks up from the grass
Pepper exploring the back yard Photo via Unsplash
A gray cat curled up but keeping an eye out
Shadow pretending not to watch the treat jar Photo via Unsplash
<quiet-lightbox id="lightbox__captions" label="Cat photos">
  <figure>
    <a href="https://images.unsplash.com/photo-1595252849939-1ec8070a354a?q=80&w=2000&auto=format&fit=crop">
      <img src="https://images.unsplash.com/photo-1595252849939-1ec8070a354a?q=80&w=600&auto=format&fit=crop" alt="A gray and white kitten looks up from the grass">
    </a>
    <figcaption>
      <strong>Pepper</strong> exploring the back yard
      <small>Photo via <a href="https://unsplash.com/" target="_blank" rel="noreferrer noopener">Unsplash</a></small>
    </figcaption>
  </figure>
  <figure>
    <a href="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=2000&auto=format&fit=crop">
      <img src="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=600&auto=format&fit=crop" alt="A gray cat curled up but keeping an eye out">
    </a>
    <figcaption>
      <strong>Shadow</strong> pretending not to watch the <em>treat jar</em>
      <small>Photo via <a href="https://unsplash.com/" target="_blank" rel="noreferrer noopener">Unsplash</a></small>
    </figcaption>
  </figure>
</quiet-lightbox>

<style>
  #lightbox__captions {
    display: flex;
    flex-wrap: wrap;
    gap: 1rem;

    figure {
      width: 260px;
      margin: 0;
    }

    /* Only the thumbnail link is a picture; the caption's link stays inline */
    figure > a {
      display: block;
      aspect-ratio: 4 / 3;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-sm);

      img {
        width: 100%;
        height: 100%;
        object-fit: cover;
      }
    }

    figcaption {
      font-size: 0.9375rem;
      line-height: 1.4;

      small {
        display: block;
        margin-block-start: 0.25rem;
        color: var(--quiet-text-muted);
        font-size: 0.8125rem;
      }
    }
  }
</style>

Opening and closing lightboxes Jump to heading

Clicking an item will open the lightbox. You can also open it from any button in the document by adding the data-lightbox="open *" attribute, where * is the lightbox's id. To start on a specific item, add its index or its id after that, e.g. data-lightbox="open gallery 2". Without one, the lightbox will open on the current activeIndex, which is the last item viewed. Similarly, you can add data-lightbox="close", data-lightbox="next", or data-lightbox="previous" to any button inside the lightbox to control it without additional scripting.

Hidden items are still part of the lightbox, so you can show a few thumbnails on the page and use a "View all" button to open the full set.

Open first photo Open second photo (by index) Open third photo (by ID)
<quiet-lightbox id="lightbox__opening">
  <a href="https://images.unsplash.com/photo-1517451330947-7809dead78d5?q=80&w=2000&auto=format&fit=crop" hidden>
    <img src="https://images.unsplash.com/photo-1517451330947-7809dead78d5?q=80&w=500&auto=format&fit=crop" alt="A tabby cat lounges in a basket by a sunny window">
  </a>
  <a href="https://images.unsplash.com/photo-1752996985167-0b907781bdee?q=80&w=2000&auto=format&fit=crop" hidden>
    <img src="https://images.unsplash.com/photo-1752996985167-0b907781bdee?q=80&w=500&auto=format&fit=crop" alt="A gray cat lies among ferns">
  </a>
  <a href="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=2000&auto=format&fit=crop" id="lightbox__opening-shadow" hidden>
    <img src="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=500&auto=format&fit=crop" alt="A gray cat curled up but keeping an eye out">
  </a>
</quiet-lightbox>

<div style="display: flex; flex-wrap: wrap; gap: 0.5rem;">
  <quiet-button data-lightbox="open lightbox__opening 0">Open first photo</quiet-button>
  <quiet-button data-lightbox="open lightbox__opening 1">Open second photo (by index)</quiet-button>
  <quiet-button data-lightbox="open lightbox__opening lightbox__opening-shadow">Open third photo (by ID)</quiet-button>
</div>

You can also control the lightbox programmatically by obtaining a reference to it and setting the open and activeIndex properties, or by calling the next(), previous(), and goTo() methods.

const lightbox = document.querySelector('quiet-lightbox');

// Open on the third item
lightbox.activeIndex = 2;
lightbox.open = true;

// Move around
lightbox.next();
lightbox.previous();
lightbox.goTo('shadow'); // by index or by the link's id

// Close the lightbox
lightbox.open = false;

Invokers look for the lightbox in their own document or shadow root, so a button inside another component's shadow DOM won't find a lightbox on the page. In that case, set the open property with JavaScript instead.

Showing thumbnails Jump to heading

Add the with-thumbnails attribute to show a strip of thumbnails at the bottom of the lightbox. The strip stays in sync as you move between items, keeping the current item's thumbnail centered. Selecting a thumbnail will show its item. To change the size of the thumbnails, set the --thumbnail-size custom property.

By default, each thumbnail uses the image inside its link, or data-poster for videos. Items without an image will show an icon instead. To use a different image, add the data-thumbnail attribute to the link and set it to the image's URL. Note that thumbnails are hidden on very short screens, such as a phone in landscape, and when the lightbox only has one item.

A black and white cat gazes upward A gray kitten practices prowling on a brown floor A tabby kitten yawns while lying on a patio A gray and white cat sleeps on a blanket with evening lights in the background A kitten lies on a bed with her head upside down
<quiet-lightbox id="lightbox__thumbnails" with-thumbnails>
  <a href="https://images.unsplash.com/photo-1516310789627-2ff305829fbb?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1516310789627-2ff305829fbb?q=80&w=500&auto=format&fit=crop" alt="A black and white cat gazes upward">
  </a>
  <a href="https://images.unsplash.com/photo-1597239351814-a5f03b4663c0?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1597239351814-a5f03b4663c0?q=80&w=500&auto=format&fit=crop" alt="A gray kitten practices prowling on a brown floor">
  </a>
  <a href="https://images.unsplash.com/photo-1622273414093-27fd902ac078?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1622273414093-27fd902ac078?q=80&w=500&auto=format&fit=crop" alt="A tabby kitten yawns while lying on a patio">
  </a>
  <a href="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=500&auto=format&fit=crop" alt="A gray and white cat sleeps on a blanket with evening lights in the background">
  </a>
  <a href="https://images.unsplash.com/photo-1513977055326-8ae6272d90a7?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1513977055326-8ae6272d90a7?q=80&w=500&auto=format&fit=crop" alt="A kitten lies on a bed with her head upside down">
  </a>
</quiet-lightbox>

<style>
  #lightbox__thumbnails {
    display: grid;
    grid-template-columns: repeat(auto-fill, minmax(110px, 1fr));
    gap: 0.5rem;

    a {
      display: block;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }
</style>

Zooming images Jump to heading

Images can be zoomed by clicking, double-tapping, or pinching them. With a mouse or trackpad, you can also hold while scrolling, or use the zoom button in the toolbar. When zoomed, you can drag the image to move it around.

To disable zooming, add the without-zoom attribute. This will also remove the zoom button, and touch devices will use the browser's native pinch zoom instead.

An orange cat sleeps peacefully at the edge of a bed A gray cat curled up but keeping an eye out
<quiet-lightbox id="lightbox__zooming">
  <a href="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=4000&auto=format&fit=crop" data-caption="Meowy McGee, whiskers and all">
    <img src="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=500&auto=format&fit=crop" alt="An orange cat sleeps peacefully at the edge of a bed">
  </a>
  <a href="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=4000&auto=format&fit=crop" data-caption="Shadow, up close">
    <img src="https://images.unsplash.com/photo-1518143099890-1e8a03745563?q=80&w=500&auto=format&fit=crop" alt="A gray cat curled up but keeping an eye out">
  </a>
</quiet-lightbox>

<style>
  #lightbox__zooming {
    display: flex;
    gap: 0.5rem;

    a {
      display: block;
      width: 140px;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }
</style>

Images can't be zoomed past their full resolution, so link to a larger image if you want users to see fine details. Videos, iframes, and inline HTML can't be zoomed.

You can also zoom programmatically by calling the zoomIn(), zoomOut(), zoomTo(), and resetZoom() methods. The readonly zoom property holds the current zoom level, where 1 means the image fits the viewer. The quiet-zoom-change event will be emitted when the zoom level changes.

const lightbox = document.querySelector('quiet-lightbox');

lightbox.zoomTo(3);
lightbox.resetZoom();

lightbox.addEventListener('quiet-zoom-change', event => {
  console.log(`Zoomed to ${event.detail.zoom}`);
});

Looping navigation Jump to heading

Add the loop attribute to let the previous and next buttons wrap around at the ends. Moving from the last item to the first will fade between them instead of scrolling through the entire gallery.

A gray cat lies among ferns A tabby kitten looks at the camera from a bed Three gray kittens on a wood floor A long-haired cat sits in a field of orange flowers
<quiet-lightbox id="lightbox__looping" loop>
  <a href="https://images.unsplash.com/photo-1752996985167-0b907781bdee?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1752996985167-0b907781bdee?q=80&w=500&auto=format&fit=crop" alt="A gray cat lies among ferns">
  </a>
  <a href="https://images.unsplash.com/photo-1625060241508-22488e1e9264?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1625060241508-22488e1e9264?q=80&w=500&auto=format&fit=crop" alt="A tabby kitten looks at the camera from a bed">
  </a>
  <a href="https://images.unsplash.com/photo-1570018144715-43110363d70a?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1570018144715-43110363d70a?q=80&w=500&auto=format&fit=crop" alt="Three gray kittens on a wood floor">
  </a>
  <a href="https://images.unsplash.com/photo-1589538923929-76e12402048b?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1589538923929-76e12402048b?q=80&w=500&auto=format&fit=crop" alt="A long-haired cat sits in a field of orange flowers">
  </a>
</quiet-lightbox>

<style>
  #lightbox__looping {
    display: flex;
    flex-wrap: wrap;
    gap: 0.5rem;

    a {
      display: block;
      width: 140px;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }
</style>

Showing videos Jump to heading

Add data-lightbox="video" to a link that points to a video file to play it in the lightbox. The thumbnail will be used as the video's poster, or you can provide one with data-poster if the link doesn't have an image. If you'd like the video to start playing as soon as it's shown, add the data-autoplay attribute. Videos will pause automatically when you move to another item or close the lightbox.

By default, videos fill the lightbox at a 16:9 aspect ratio. For other aspect ratios, such as vertical video, set data-aspect-ratio on the link.

A cat plays with its owner on a couch
<quiet-lightbox id="lightbox__videos">
  <a
    href="https://assets.mixkit.co/videos/1779/1779-720.mp4"
    data-lightbox="video"
    data-caption="Pixel, supervising"
    data-autoplay
  >
    <img src="https://assets.mixkit.co/videos/1779/1779-thumb-360-0.jpg" alt="A cat plays with its owner on a couch">
    <span class="play">
      <quiet-icon name="player-play" family="filled"></quiet-icon>
    </span>
  </a>
</quiet-lightbox>

<style>
  #lightbox__videos {
    a {
      display: block;
      position: relative;
      width: 240px;
      aspect-ratio: 16 / 9;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      display: block;
      width: 100%;
      height: 100%;
      object-fit: cover;
    }

    /* A play badge centered over the thumbnail, nudged right so the triangle looks centered */
    .play {
      display: flex;
      position: absolute;
      align-items: center;
      justify-content: center;
      width: 3.5rem;
      height: 3.5rem;
      margin: auto;
      inset: 0;
      border-radius: var(--quiet-border-radius-circle);
      background-color: rgb(0 0 0 / 0.5);
      color: white;
      backdrop-filter: blur(4px);

      quiet-icon {
        font-size: 1.75rem;
        translate: 0.125rem 0;
      }
    }
  }
</style>

To add captions with <track> or offer multiple <source> formats, use an inline HTML item with your own <video> element.

Embedding iframes Jump to heading

Add data-lightbox="iframe" to a link to show its href in an iframe. This is useful for showing videos from YouTube, Vimeo, and similar services. Remember to use the service's embed URL instead of the URL you'd normally share. By default, iframes use a 16:9 aspect ratio, but you can change that per item with data-aspect-ratio.

Iframes are created when their item becomes active and removed when the user moves to another item, so embedded players will stop playing automatically.

Watch on YouTube
<quiet-lightbox id="lightbox__iframes">
  <quiet-button data-lightbox="open lightbox__iframes">
    <quiet-icon slot="start" name="brand-youtube"></quiet-icon>
    Watch on YouTube
  </quiet-button>
  <a href="https://www.youtube.com/embed/1cjdxjT5hkU?autoplay=1" data-lightbox="iframe" data-caption="Cats being cats" hidden>Watch the video</a>
</quiet-lightbox>

Touch gestures that start inside an iframe are handled by the embedded page, so swiping to dismiss only works from the area around the iframe.

Showing inline HTML Jump to heading

Lightboxes can show more than images and videos. Add data-lightbox="html" to a link whose href is the id of an element inside the lightbox and that element will be shown as an item. This is useful for content the lightbox can't render on its own, such as a comparison slider, an enlarged chart or diagram, a screenshot in a browser frame, a map, an SVG, or a <video> with captions. The element must be a direct child of <quiet-lightbox>. It stays hidden on the page and is shown as-is when its item is active, so its styles, event listeners, and state remain intact. Note that the element will need its own dimensions.

Inline HTML uses the page's theme, not the lightbox's dark appearance. Add the quiet-dark class to an item to match the viewer, and give text content a background such as var(--quiet-background-color), as shown in the chart below. Forms inside inline HTML should close the lightbox with a data-lightbox="close" button instead of method="dialog".

An orange cat in a grayscale photo A gray tabby kitten meows An orange cat looks at the camera The same orange cat in a grayscale photo A gray tabby kitten meows
<quiet-lightbox id="lightbox__html" label="Shelter report">
  <a href="#lightbox__html-comparison" data-lightbox="html" data-caption="Drag the handle to compare">
    <img src="https://images.unsplash.com/photo-1671707696618-ca0685b0012e?q=80&w=500&sat=-100&bri=-15&auto=format&fit=crop" alt="An orange cat in a grayscale photo">
    <quiet-icon name="arrows-horizontal"></quiet-icon>
  </a>
  <a href="#lightbox__html-chart" data-lightbox="html" data-caption="Treats consumed this year">
    <quiet-chart class="preview" label="Treats consumed this year" without-legend without-tooltip without-animation></quiet-chart>
  </a>
  <a href="#lightbox__html-frame" data-lightbox="html" data-caption="The new adoption page">
    <quiet-browser-frame class="preview" label="meowy.example" flush>
      <img src="https://images.unsplash.com/photo-1600440090763-b942f3c562b6?q=80&w=600&auto=format&fit=crop" alt="A gray tabby kitten meows">
    </quiet-browser-frame>
  </a>

  <quiet-comparison id="lightbox__html-comparison">
    <img slot="start" src="https://images.unsplash.com/photo-1671707696618-ca0685b0012e?q=80&w=1600&auto=format&fit=crop" alt="An orange cat looks at the camera">
    <img slot="end" src="https://images.unsplash.com/photo-1671707696618-ca0685b0012e?q=80&w=1600&sat=-100&bri=-15&auto=format&fit=crop" alt="The same orange cat in a grayscale photo">
  </quiet-comparison>

  <quiet-chart id="lightbox__html-chart" class="quiet-dark" chart-title="Treats Consumed" label="Treats consumed this year"></quiet-chart>

  <quiet-browser-frame id="lightbox__html-frame" label="meowy.example/adopt" flush>
    <img src="https://images.unsplash.com/photo-1600440090763-b942f3c562b6?q=80&w=1600&auto=format&fit=crop" alt="A gray tabby kitten meows">
  </quiet-browser-frame>
</quiet-lightbox>

<script>
  const container = document.getElementById('lightbox__html');
  const data = {
    labels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun'],
    datasets: [
      { label: 'Meowy', data: [42, 38, 51, 47, 60, 55] },
      { label: 'Whiskers', data: [30, 34, 29, 41, 37, 44] }
    ]
  };

  // The preview and the full-size chart share the same data
  container.querySelectorAll('quiet-chart').forEach(chart => (chart.data = data));
</script>

<style>
  #lightbox__html {
    display: flex;
    flex-wrap: wrap;
    gap: 1rem;

    a {
      display: grid;
      width: 200px;
      aspect-ratio: 3 / 2;
      padding: 0.5rem;
      overflow: hidden;
      border: solid var(--quiet-border-width) var(--quiet-neutral-stroke-softer);
      border-radius: var(--quiet-border-radius-md);
      background-color: var(--quiet-paper-color);
      color: white;
      place-items: center;
      transition: 100ms border-color ease;

      &:hover {
        border-color: var(--quiet-neutral-stroke-mid);
      }

      > * {
        grid-area: 1 / 1;
      }

      > img {
        width: 100%;
        height: 100%;
        object-fit: cover;
        border-radius: var(--quiet-border-radius-sm);
      }
    }

    quiet-icon {
      font-size: 2rem;
      filter: drop-shadow(0 1px 4px rgb(0 0 0 / 0.5));
    }

    /* Previews are just pictures of the real thing */
    .preview {
      width: 100%;
      pointer-events: none;
    }
  }

  /* Each item sizes itself to fit the viewer */
  #lightbox__html-comparison,
  #lightbox__html-frame {
    width: min(90vw, 60rem);
  }

  #lightbox__html-chart {
    width: min(90vw, 50rem);
    padding: 1.5rem;
    border-radius: var(--quiet-border-radius-md);
    background-color: var(--quiet-background-color);
  }
</style>

Inline HTML items may render briefly before the lightbox upgrades. Add the quiet-cloak class to prevent the flash.

Hiding navigation and the counter Jump to heading

You can hide the previous and next buttons by adding the without-nav attribute. To hide the "1 of 5" counter, use the without-counter attribute. Hidden navigation buttons remain available to keyboard users and assistive devices, and swiping continues to work. Note that both are hidden automatically when a lightbox only has one item. The previous and next buttons are also hidden on touch devices, where users can swipe between items.

On touch devices, tapping an image will hide the toolbar, navigation, caption, and thumbnails so only the image is shown. Tapping again will bring them back.

A gray kitten practices prowling on a brown floor A gray and white cat sleeps on a blanket with evening lights in the background
<quiet-lightbox id="lightbox__without" without-nav without-counter>
  <a href="https://images.unsplash.com/photo-1597239351814-a5f03b4663c0?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1597239351814-a5f03b4663c0?q=80&w=500&auto=format&fit=crop" alt="A gray kitten practices prowling on a brown floor">
  </a>
  <a href="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=2000&auto=format&fit=crop">
    <img src="https://images.unsplash.com/photo-1737912031624-e17ba0d7f673?q=80&w=500&auto=format&fit=crop" alt="A gray and white cat sleeps on a blanket with evening lights in the background">
  </a>
</quiet-lightbox>

<style>
  #lightbox__without {
    display: flex;
    gap: 0.5rem;

    a {
      display: block;
      width: 140px;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }
  }
</style>

Customizing actions Jump to heading

By default, the toolbar provides a zoom button for images and a close button. You can add your own actions by slotting buttons into the actions slot. Note that adding your own actions will remove the default buttons, so add a close button back with data-lightbox="close". If you want zoom buttons, use data-lightbox="zoom-in" and data-lightbox="zoom-out". Each slotted action will sit on the same translucent circle as the default buttons, so you can add the pill attribute to text buttons to match its shape. Use the activeItem property along with the quiet-item-change event to update your actions when the item changes. This example adds a toggle icon that remembers your favorites, a share button, and a download button.

A sleepy cat looks up in dim, hazy purple lighting A tabby cat lounges in a basket by a sunny window
<quiet-lightbox id="lightbox__actions">
  <quiet-toggle-icon slot="actions" label="Favorite" effect="scale" id="lightbox__actions-favorite">
    <quiet-icon slot="unchecked" name="heart" family="outline"></quiet-icon>
    <quiet-icon slot="checked" name="heart" family="filled"></quiet-icon>
  </quiet-toggle-icon>
  <quiet-share slot="actions" id="lightbox__actions-share">
    <quiet-button appearance="text" pill icon-label="Share">
      <quiet-icon name="share-3"></quiet-icon>
    </quiet-button>
  </quiet-share>
  <quiet-button slot="actions" appearance="text" pill icon-label="Download" id="lightbox__actions-download">
    <quiet-icon name="download"></quiet-icon>
  </quiet-button>
  <quiet-button slot="actions" appearance="text" pill icon-label="Close" data-lightbox="close">
    <quiet-icon name="x"></quiet-icon>
  </quiet-button>

  <a href="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=2000&auto=format&fit=crop" data-caption="Luna">
    <img src="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=500&auto=format&fit=crop" alt="A sleepy cat looks up in dim, hazy purple lighting">
  </a>
  <a href="https://images.unsplash.com/photo-1517451330947-7809dead78d5?q=80&w=2000&auto=format&fit=crop" data-caption="Sunny">
    <img src="https://images.unsplash.com/photo-1517451330947-7809dead78d5?q=80&w=500&auto=format&fit=crop" alt="A tabby cat lounges in a basket by a sunny window">
  </a>
</quiet-lightbox>

<script>
  const lightbox = document.getElementById('lightbox__actions');
  const favorite = document.getElementById('lightbox__actions-favorite');
  const share = document.getElementById('lightbox__actions-share');
  const downloadButton = document.getElementById('lightbox__actions-download');
  const favorites = new Set();

  // Point every action at the active item
  function updateActions() {
    const item = lightbox.activeItem;
    favorite.checked = favorites.has(item);
    share.label = item.dataset.caption;
    share.url = item.href;
  }

  // Browsers ignore the download attribute for cross-origin links, so fetch the image and download it as a blob
  downloadButton.addEventListener('click', async () => {
    const url = new URL(lightbox.activeItem.href);
    downloadButton.loading = true;

    try {
      const blob = await (await fetch(url)).blob();
      const link = document.createElement('a');
      link.href = URL.createObjectURL(blob);
      link.download = url.pathname.split('/').pop();
      link.click();
      URL.revokeObjectURL(link.href);
    } finally {
      downloadButton.loading = false;
    }
  });

  // Remember the choice for this item
  favorite.addEventListener('quiet-change', () => {
    const item = lightbox.activeItem;
    if (favorite.checked) {
      favorites.add(item);
    } else {
      favorites.delete(item);
    }
  });

  lightbox.addEventListener('quiet-before-open', updateActions);
  lightbox.addEventListener('quiet-item-change', updateActions);
</script>

<style>
  #lightbox__actions {
    display: flex;
    gap: 0.5rem;

    a {
      display: block;
      width: 140px;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }

    /* Match the heart to the toolbar's other icons */
    quiet-toggle-icon {
      --unchecked-color: currentColor;
      --checked-color: var(--quiet-destructive-text-colorful);
    }
  }
</style>

For same-origin images, setting href and download on the button is all you need. Cross-origin images need to be fetched first, as shown here, and the server must allow it with CORS.

Listening for changes Jump to heading

Listen for the quiet-item-change event to know when the user moves to another item. The new index is available in event.detail.index and the item's link in event.detail.item. If an image or video fails to load, the lightbox will show a message in its place and emit the quiet-load-error event with the same details. The quiet-before-open, quiet-open, quiet-before-close, and quiet-close events work the same way they do for dialogs.

const lightbox = document.querySelector('quiet-lightbox');

lightbox.addEventListener('quiet-item-change', event => {
  console.log(`Now viewing item ${event.detail.index}`, event.detail.item);
});

lightbox.addEventListener('quiet-before-close', event => {
  // Call event.preventDefault() to keep the lightbox open
});

Mismatched thumbnails Jump to heading

Thumbnails don't have to match their full-size images. When they're different, the zoom animation will start with the thumbnail and transition to the full-size image as it loads. In this example, the first thumbnail is a square crop of a landscape photo, the second is a square crop that uses data-width and data-height to provide the full-size image's dimensions, and the third opens a different photo entirely.

A kitten lies on a bed with her head upside down A sleepy cat looks up in dim, hazy purple lighting Three gray kittens on a wood floor
<quiet-lightbox id="lightbox__mismatched" label="Mismatched thumbnails">
  <a href="https://images.unsplash.com/photo-1513977055326-8ae6272d90a7?q=80&w=2000&auto=format&fit=crop" data-caption="A square crop, no size hints">
    <img src="https://images.unsplash.com/photo-1513977055326-8ae6272d90a7?q=80&w=500&h=500&auto=format&fit=crop" alt="A kitten lies on a bed with her head upside down">
  </a>
  <a href="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=2000&auto=format&fit=crop" data-width="2000" data-height="1333" data-caption="A square crop, with size hints">
    <img src="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=500&h=500&auto=format&fit=crop" alt="A sleepy cat looks up in dim, hazy purple lighting">
  </a>
  <a href="https://images.unsplash.com/photo-1516310789627-2ff305829fbb?q=80&w=2000&auto=format&fit=crop" data-caption="You clicked the triplets and got Peanut">
    <img src="https://images.unsplash.com/photo-1570018144715-43110363d70a?q=80&w=500&h=500&auto=format&fit=crop" alt="Three gray kittens on a wood floor">
  </a>
</quiet-lightbox>

<style>
  #lightbox__mismatched {
    display: flex;
    flex-wrap: wrap;
    gap: 0.5rem;

    a {
      display: block;
      width: 140px;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      display: block;
      width: 100%;
      height: auto;
    }
  }
</style>

Styling lightboxes Jump to heading

Lightboxes come with a simple, minimal appearance. Feel free to customize them with your own styles. You can change the scrim with the --backdrop-color custom property, which accepts any background including gradients, and adjust the animations with the --show-duration and --hide-duration custom properties. The toolbar, navigation, and caption use design tokens, so you can restyle them by setting tokens on their parts. To decorate images, use outline or box-shadow on the image part instead of border or padding, which will cause the image to shift at the end of the zoom animation.

An orange cat sleeps peacefully at the edge of a bed A sleepy cat looks up in dim, hazy purple lighting A kitten sleeps peacefully on the floor
<quiet-lightbox id="lightbox__styling" label="Space cats">
  <a href="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=2000&auto=format&fit=crop" data-caption="Meowy McGee, first cat on the moon">
    <img src="https://images.unsplash.com/photo-1626603084013-1bf8c6627707?q=80&w=500&auto=format&fit=crop" alt="An orange cat sleeps peacefully at the edge of a bed">
  </a>
  <a href="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=2000&auto=format&fit=crop" data-caption="Luna, naturally">
    <img src="https://images.unsplash.com/photo-1664037170371-045dee5604a3?q=80&w=500&auto=format&fit=crop" alt="A sleepy cat looks up in dim, hazy purple lighting">
  </a>
  <a href="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=2000&auto=format&fit=crop" data-caption="Mochi, drifting through the void">
    <img src="https://images.unsplash.com/photo-1707520595303-d6b499aa84af?q=80&w=500&auto=format&fit=crop" alt="A kitten sleeps peacefully on the floor">
  </a>
</quiet-lightbox>

<style>
  #lightbox__styling {
    /* An aurora. Layers are listed top to bottom. */
    --backdrop-color:
      radial-gradient(60% 55% at 12% 8%, rgb(129 140 248 / 0.55), transparent 70%),
      radial-gradient(55% 65% at 88% 92%, rgb(244 114 182 / 0.45), transparent 70%),
      radial-gradient(45% 40% at 70% 18%, rgb(94 234 212 / 0.3), transparent 70%),
      linear-gradient(160deg, rgb(10 8 30 / 0.97), rgb(28 10 48 / 0.97));
    --show-duration: 600ms;
    --hide-duration: 400ms;
    --spacing: 1.5rem;

    display: flex;
    gap: 0.5rem;

    a {
      display: block;
      width: 140px;
      aspect-ratio: 1;
      overflow: hidden;
      border-radius: var(--quiet-border-radius-md);
    }

    img {
      width: 100%;
      height: 100%;
      object-fit: cover;
    }

    /* Tint the chrome to match */
    &::part(toolbar),
    &::part(previous-button),
    &::part(next-button),
    &::part(caption) {
      --quiet-text-body: rgb(237 233 254);
      --quiet-text-muted: rgb(196 181 253 / 0.7);
      --quiet-neutral-text-on-soft: rgb(237 233 254);
      --quiet-neutral-fill-softer: rgb(139 92 246 / 0.25);
      --quiet-neutral-fill-soft: rgb(139 92 246 / 0.45);
    }

    /* Glassy arrows */
    &::part(previous-button__button),
    &::part(next-button__button) {
      border: solid 1px rgb(255 255 255 / 0.15);
      backdrop-filter: blur(8px);
    }

    /* The glow blooms in as the photo lands */
    &::part(image) {
      border-radius: var(--quiet-border-radius-lg);
      outline: solid 1px rgb(255 255 255 / 0.12);
      outline-offset: -1px;
      box-shadow:
        0 30px 80px rgb(0 0 0 / 0.6),
        0 0 140px rgb(168 85 247 / 0.4);
    }

    &::part(counter) {
      letter-spacing: 0.1em;
      text-transform: uppercase;
    }

    &::part(caption) {
      font-family: Georgia, 'Times New Roman', serif;
      font-size: 1.25rem;
      font-style: italic;
    }
  }
</style>

Keyboard support Jump to heading

When the lightbox is open, you can use the following keys to navigate.

Key Action
โ† Shows the previous item (RTL: next)
โ†’ Shows the next item (RTL: previous)
Home Jumps to the first item
End Jumps to the last item
+ - Zooms the image in or out
0 Returns the image to its fitted size
โ† โ†’ โ†‘ โ†“ Moves around the image (when zoomed)
Escape Closes the lightbox
Tab Moves focus between the toolbar, navigation buttons, thumbnails, and the active item's content

API Jump to heading

Importing Jump to heading

The autoloader is the recommended way to import components but, if you prefer to do it manually, the following code snippets will be helpful.

CDN Self-hosted

To manually import <quiet-lightbox> from the CDN, use the following code.

import 'https://cdn.quietui.org/v6.7.0/components/lightbox/lightbox.js';

To manually import <quiet-lightbox> from a self-hosted distribution, use the following code. Remember to replace /path/to/quiet with the appropriate local path.

import '/path/to/quiet/components/lightbox/lightbox.js';

Slots Jump to heading

Lightbox supports the following slots. Learn more about using slots

Name Description
(default) The gallery's thumbnails and links, rendered in place. Any <a href> that contains an <img> or has a data-lightbox type becomes an item. Elements referenced by data-lightbox="html" links must also be direct children.
previous-icon A custom icon for the previous button. Default icons flip in RTL, so provide one that suits your direction.
next-icon A custom icon for the next button.
close-icon A custom icon for the default close button.
zoom-in-icon A custom icon for the default zoom button when the image isn't zoomed.
zoom-out-icon A custom icon for the default zoom button when the image is zoomed.
actions One or more buttons to show in the toolbar. Slotting actions removes the default zoom and close buttons, so add them back with data-lightbox="zoom-in", data-lightbox="zoom-out", and data-lightbox="close" if you need them.

Properties Jump to heading

Lightbox has the following properties that can be set with corresponding attributes. In many cases, the attribute's name is the same as the property's name. If an attribute is different, it will be displayed after the property. Learn more about attributes and properties

Property Description Reflects Type Default
open Opens or closes the lightbox. boolean false
activeIndex
active-index
The index of the active item. Set it before opening to start on a specific item. number 0
loop Allows previous and next navigation to wrap around at the ends. boolean false
label The lightbox's accessible name. This won't be visible, but it will be read to assistive devices. string ''
withoutNav
without-nav
Hides the previous and next buttons visually. They remain available to assistive devices and keyboard users. boolean false
withoutCounter
without-counter
Hides the "1 of 10" counter. boolean false
withoutZoom
without-zoom
Disables zooming and removes the zoom button. The browser's own pinch zoom takes over on touch devices. boolean false
withThumbnails
with-thumbnails
Shows a strip of thumbnails along the bottom that follows along as the user moves between items. Selecting a thumbnail shows its item. boolean false
items The links that represent the lightbox's items, in order. HTMLAnchorElement[]
activeItem The link that represents the active item, or null when the lightbox has no items. HTMLAnchorElement | null
hasNext Whether there's an item after the active one. boolean
hasPrevious Whether there's an item before the active one. boolean
zoom The active image's zoom level, where 1 fits the image to the viewer. number

Methods Jump to heading

Lightbox supports the following methods. You can obtain a reference to the element and call them like functions in JavaScript. Learn more about methods

Name Description Arguments
next() Shows the next item. Wraps around to the first item when loop is enabled.
previous() Shows the previous item. Wraps around to the last item when loop is enabled.
goTo() Shows a specific item by index or by the id of its link. indexOrId: number | string
zoomIn() Zooms the active image in by one step. A no-op when the active item isn't an image or without-zoom is set.
zoomOut() Zooms the active image out by one step.
zoomTo() Zooms the active image to a specific level. The level is kept between 1 and the image's full resolution. zoom: number
resetZoom() Returns the active image to its fitted size.

Events Jump to heading

Lightbox dispatches the following custom events. You can listen to them the same way was native events. Learn more about custom events

Name Description
quiet-before-open Emitted when the lightbox is instructed to open but before it is shown. Calling event.preventDefault() will prevent the lightbox from opening.
quiet-open Emitted after the lightbox has been opened and the show animation has completed.
quiet-before-close Emitted when the lightbox is dismissed. Calling event.preventDefault() will prevent the lightbox from closing. You can inspect event.detail.source to see which element caused the lightbox to close.
quiet-close Emitted after the lightbox has been closed and the hide animation has completed.
quiet-item-change Emitted when the active item changes while the lightbox is open. event.detail.index is the new index and event.detail.item is the link that represents it.
quiet-load-error Emitted when an item's image or video fails to load. event.detail.index is the item's index and event.detail.item is its link.
quiet-zoom-change Emitted when the active image's zoom level changes. The new zoom level is available in event.detail.zoom.

CSS custom properties Jump to heading

Lightbox supports the following CSS custom properties. You can style them like any other CSS property. Learn more about CSS custom properties

Name Description Default
--show-duration The duration of the show animation. 300ms
--hide-duration The duration of the hide animation. 250ms
--backdrop-color The scrim behind the content, which is more opaque in light mode. Accepts any background, including gradients. light-dark(color-mix(in oklab, var(--quiet-neutral-950), transparent 3%), color-mix(in oklab, var(--quiet-neutral-950), transparent 8%))
--item-gap The gap between items so neighbors don't peek in while swiping. 2rem
--spacing The spacing used around the toolbar, navigation, caption, thumbnails, and content. 1rem
--caption-width The maximum width of the caption's text. 40rem
--thumbnail-size The width and height of each thumbnail in the thumbnail strip. 3rem

CSS parts Jump to heading

Lightbox exposes internal elements that can be styled with CSS using the selectors shown below. Learn more about CSS parts

Name Description CSS selector
dialog The internal <dialog> element. ::part(dialog)
toolbar The bar at the top that holds the counter and actions. ::part(toolbar)
counter The "1 of 10" counter. ::part(counter)
close-button The default close button, a <quiet-button> element. ::part(close-button)
close-button__button The close button's button part. ::part(close-button__button)
zoom-button The default zoom button, a <quiet-button> element. ::part(zoom-button)
zoom-button__button The zoom button's button part. ::part(zoom-button__button)
previous-button The previous button, a <quiet-button> element. ::part(previous-button)
previous-button__button The previous button's button part. ::part(previous-button__button)
next-button The next button, a <quiet-button> element. ::part(next-button)
next-button__button The next button's button part. ::part(next-button__button)
items The scrollable container that holds the items. ::part(items)
item Each item's slide. ::part(item)
image The full-size <img> in image items. ::part(image)
video The <video> in video items. ::part(video)
iframe The <iframe> in iframe items. ::part(iframe)
content The container that wraps inline HTML items. ::part(content)
spinner The spinner shown while an image loads, a <quiet-spinner> element. ::part(spinner)
error The message shown when an item fails to load. ::part(error)
caption The caption shown below the active item. ::part(caption)
thumbnails The strip of thumbnails shown at the bottom when with-thumbnails is set. ::part(thumbnails)
thumbnail Each thumbnail in the strip, a <button> element. ::part(thumbnail)
thumbnail-current The thumbnail of the item being viewed. ::part(thumbnail-current)

Custom States Jump to heading

Lightbox has the following custom states. You can target them with CSS using the selectors shown below. Learn more about custom states

Name Description CSS selector
open Applied when the lightbox is open. :state(open)
scrolling Applied while the items are scrolling. :state(scrolling)
dragging Applied while the user is dragging an item to dismiss the lightbox. :state(dragging)
zoomed Applied while the active image is zoomed in. :state(zoomed)
panning Applied while the user is dragging a zoomed image. :state(panning)
immersive Applied while the toolbar, navigation, caption, and thumbnails are hidden because the user tapped the image on a touch device. :state(immersive)

Dependencies Jump to heading

Lightbox automatically imports the following elements. Sub-dependencies are also included in this list.

Search this website Toggle dark mode View the code on GitHub Follow @quietui.org on Bluesky Follow @quiet_ui on X

    No results found