Lightbox
<quiet-lightbox>
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.
<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:
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.
<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.
<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.
<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.
<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
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.
<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.
<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.
<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.
<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".
<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.
<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.
<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.
<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.
<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.
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.