Font Awesome Build Awesome
Search ⌘KCtrl+K
Light Dark System Docs Color Scheme: System \ Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Theme: Default Icon Style: Classic Regular
Solid Regular Light Thin Classic Sharp Duotone Sharp Duotone
Docs Most styles require Font Awesome Pro.
Server-Side Rendering: Off Server-Side Rendering Docs
View on GitHub
Start Components Docs Help Pro
Login Log into your account
Web Awesome Font Awesome Build Awesome
Search this site… /
Light Dark System Docs Color Scheme: System \ Default Awesome Shoelace Active Brutalist Glossy Matter Mellow Playful Premium Tailspin Docs Theme: Default Icon Style: Classic Regular
Solid Regular Light Thin Classic Sharp Duotone Sharp Duotone
Docs Most styles require Font Awesome Pro.
Server-Side Rendering: Off Server-Side Rendering Docs
View on GitHub
Components Pro

Getting Started

  • Installation
  • Usage
  • Forms
  • Localization
  • Frameworks
  • Using with AI
  • Figma Design Kit ProThis requires access to Web Awesome Pro
  • Server Rendering

Resources

  • Accessibility
  • Browser Support
  • Contributing
  • Patterns ProPatterns require access to Web Awesome Pro
  • Migrating from Shoelace
  • Visual Tests
  • Changelog
  • Help & Support

Theming & Utilities

  • Overview
  • Built-in Themes
  • Color Palettes
  • Design Tokens
  • Customizing & Theming
  • CSS Utilities

Actions

  • Button
  • Button Group
  • Copy Button
  • Dropdown
    • Dropdown Item

Forms

  • Checkbox
  • Checkbox Group
  • Color Picker
  • Combobox ProThis requires access to Web Awesome Pro
  • Date Input ProThis requires access to Web Awesome Pro
  • Date Picker ProThis requires access to Web Awesome Pro
  • File Input ProThis requires access to Web Awesome Pro
  • Input
  • Known Date
  • Number Input
  • OTP Input
  • Radio Group
    • Radio
  • Rating
  • Rich Text Editor ProThis requires access to Web Awesome Pro
  • Select
    • Option
  • Slider
  • Switch
  • Tag Input
  • Textarea
  • Time Input

Layout

  • Accordion
    • Accordion Item
  • Card
  • Details
  • Dialog
  • Divider
  • Drawer
  • Page
  • Scroller
  • Split Panel

Navigation

  • Breadcrumb
    • Breadcrumb Item
  • Pagination
  • Stepper
    • Step
  • Tab Group
    • Tab
    • Tab Panel
  • Tree
    • Tree Item

Feedback

  • Badge
  • Callout
  • Progress Bar
  • Progress Ring
  • Skeleton
  • Spinner
  • Tag
  • Toast
    • Toast Item
  • Tooltip

Media

  • Animated Image
  • Avatar
  • Carousel
    • Carousel Item
  • Code Highlighter
  • Comparison
  • Icon
  • Lightbox
    • Lightbox Item
  • Markdown
  • QR Code
  • Video ProThis requires access to Web Awesome Pro
  • Video Playlist ProThis requires access to Web Awesome Pro
  • Zoomable Frame

Data Viz ProThis requires access to Web Awesome Pro

  • Bar Chart
  • Bubble Chart
  • Data Grid
  • Doughnut Chart
  • Line Chart
  • Pie Chart
  • Polar Area Chart
  • Radar Chart
  • Scatter Chart
  • Sparkline
  • Advanced Usage

Helpers

  • Animation
  • Counter
  • Format Bytes
  • Format Date
  • Format Number
  • Include
  • Intersection Observer
  • Mutation Observer
  • Number Ticker
  • Popover
  • Popup
  • Random Content
  • Relative Time
  • Resize Observer

Lightbox

  • Examples
  • Caption
  • Thumbnails
  • Loop
  • Hiding Controls
  • Image Dimensions
  • Responsive Images
  • Video
  • Custom Content
  • Single Image
  • Images in an Article
  • Items Without Thumbnails
  • Customizing
  • Opening & Closing Declaratively
  • Opening Programmatically
  • Toolbar Actions
  • Preventing the Lightbox from Closing
  • Accessibility Considerations
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • Methods
  • Events
  • CSS Custom Properties
  • Custom States
  • CSS Parts
  • Dependencies
On This Page...
  • Examples
  • Caption
  • Thumbnails
  • Loop
  • Hiding Controls
  • Image Dimensions
  • Responsive Images
  • Video
  • Custom Content
  • Single Image
  • Images in an Article
  • Items Without Thumbnails
  • Customizing
  • Opening & Closing Declaratively
  • Opening Programmatically
  • Toolbar Actions
  • Preventing the Lightbox from Closing
  • Accessibility Considerations
  • API
  • Importing
  • Slots
  • Attributes & Properties
  • Methods
  • Events
  • CSS Custom Properties
  • Custom States
  • CSS Parts
  • Dependencies

Lightbox

<wa-lightbox>
Experimental Media Since 3.15

Lightboxes show images and videos in a full-screen viewer that opens from their thumbnails. Use them for photo galleries, product images, or any media that deserves a closer look.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field A field of grass with the sun setting in the background
<wa-lightbox class="wa-grid lightbox-overview" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    caption="Sunlight breaking over the mountains. Photo by Adam Kool on Unsplash."
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    caption="A river winding through an evergreen forest. Photo by Luca Bravo on Unsplash."
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    caption="Sunset over a lavender field. Photo by Leonard Cotte on Unsplash."
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=1600&h=1067&fit=crop&q=80"
    caption="Evening light across a field of grass. Photo by Sapan Patel on Unsplash."
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=480&h=320&fit=crop&q=60"
      alt="A field of grass with the sun setting in the background"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-overview {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Wrap each thumbnail in a <wa-lightbox-item> and set the item's src attribute to the full-size image. Click a thumbnail to open the lightbox at that item. Swipe or use the arrow keys to move between items, click or pinch to zoom, and pull up or down or press Escape to close. On touch screens, tap the image to hide the controls and tap again to bring them back.

Use the label attribute to describe the lightbox's contents to assistive devices.

The lightbox itself is a plain block element, so you can lay out the thumbnails any way you like.

Each thumbnail is a link to its full-size image.
Items still work before the component loads, and you can open one in a new tab like any other link.

Examples

Link to This Section

Caption

Link to This Section

Use the caption attribute to show text with an item in the lightbox. The caption fades out while the image is zoomed in.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field
<wa-lightbox class="wa-grid lightbox-caption" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="Sunlight breaking over the mountains. Photo by Adam Kool on Unsplash."
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="A river winding through an evergreen forest. Photo by Luca Bravo on Unsplash."
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="Sunset over a lavender field. Photo by Leonard Cotte on Unsplash."
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-caption {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Thumbnails

Link to This Section

Add the with-thumbnails attribute to show a strip of thumbnails for jumping between items.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field A field of grass with the sun setting in the background A scenic view of a mountain with clouds rolling in
<wa-lightbox class="wa-grid lightbox-thumbnails" label="Landscape photos" with-thumbnails>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=480&h=320&fit=crop&q=60"
      alt="A field of grass with the sun setting in the background"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=480&h=320&fit=crop&q=60"
      alt="A scenic view of a mountain with clouds rolling in"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-thumbnails {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Loop

Link to This Section

By default, the lightbox stops at the first and last items. Add the loop attribute to wrap around when navigating past them with the buttons or the keyboard.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field
<wa-lightbox class="wa-grid lightbox-loop" label="Landscape photos" loop>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-loop {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Hiding Controls

Link to This Section

Use these attributes to remove controls you don't need. This example hides the counter and turns off zooming.

Attribute Behavior
without-counter Hides the "3 of 12" counter.
without-zoom Turns off zooming and removes the zoom button.
without-navigation Hides the previous and next buttons. Swiping and the arrow keys still work.
The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field
<wa-lightbox class="wa-grid lightbox-controls" label="Landscape photos" without-counter without-zoom>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-controls {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Keep a way to navigate without swiping.
The previous and next buttons are hidden on touch screens, and everywhere when without-navigation is set. Add with-thumbnails so people who can't swipe can still tap their way between items.

Image Dimensions

Link to This Section

Set the width and height attributes to the full-size image's dimensions in pixels. The lightbox sizes the slide from them before the image loads, so the opening animation is exact. They also set how far the image can be zoomed. Without them, the lightbox uses the thumbnail's proportions until the image loads.

These square thumbnails open into a tall photo, a wide one, and a standard one.

A field of grass with the sun setting in the background A scenic view of a mountain with clouds rolling in The sun is setting over a lavender field
<wa-lightbox class="wa-grid lightbox-dimensions" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=1067&h=1600&fit=crop&q=80"
    caption="Evening light across a field of grass. Photo by Sapan Patel on Unsplash."
    width="1067"
    height="1600"
  >
    <img
      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=320&h=480&fit=crop&q=60"
      alt="A field of grass with the sun setting in the background"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=1600&h=900&fit=crop&q=80"
    caption="Clouds rolling in over the mountains. Photo by V2osk on Unsplash."
    width="1600"
    height="900"
  >
    <img
      src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=480&h=270&fit=crop&q=60"
      alt="A scenic view of a mountain with clouds rolling in"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    caption="Sunset over a lavender field. Photo by Leonard Cotte on Unsplash."
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-dimensions {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Crop thumbnails with CSS, not in the file.
The opening animation is smoothest when the thumbnail file has the same proportions as the full-size image. Use object-fit: cover to show it at a different shape.

Responsive Images

Link to This Section

Use the srcset attribute to offer the full-size image at more than one resolution. The lightbox picks a source for the size it's displayed at, and a sharper one when the image is zoomed in. Set the sizes attribute to override this.

<wa-lightbox-item src="photo-1600.jpg" srcset="photo-1600.jpg 1600w, photo-3200.jpg 3200w" width="3200" height="2134">
  <img src="photo-thumbnail.jpg" alt="..." />
</wa-lightbox-item>

Video

Link to This Section

Set an item's type attribute to video to play a video in the lightbox. The thumbnail gets a play button and is used as the video's poster. Videos pause when you move to another item or close the lightbox, and they can't be zoomed.

A dog wearing glasses The sun shines on the mountains and trees A river winding through an evergreen forest
<wa-lightbox class="wa-grid lightbox-video" label="Photos and videos">
  <wa-lightbox-item
    type="video"
    src="https://uploads.webawesome.com/dog-with-glasses.mp4"
    caption="A dog wearing glasses"
    width="3840"
    height="2160"
  >
    <img src="/assets/images/dog-with-glasses.jpg" alt="A dog wearing glasses" />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-video {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Custom Content

Link to This Section

Put anything other than an image or a native video in a <template> inside the item. That covers other components, video players, and embeds. The lightbox copies the template's content into the slide when it's needed, so nothing in it loads until then. Set the width and height attributes to give the slide its proportions. Custom content can't be zoomed.

This example shows a comparison in the first slide.

Kittens in a basket looking around The sun shines on the mountains and trees A river winding through an evergreen forest
<wa-lightbox class="wa-grid lightbox-content" label="Photos">
  <wa-lightbox-item width="1200" height="800" caption="Drag the divider to compare">
    <img
      src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=480&h=320&q=60"
      alt="Kittens in a basket looking around"
    />
    <template>
      <wa-comparison>
        <img
          slot="before"
          src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&h=800&q=80&sat=-100&bri=-5"
          alt="Grayscale version of kittens in a basket looking around"
        />
        <img
          slot="after"
          src="https://images.unsplash.com/photo-1517331156700-3c241d2b4d83?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1200&h=800&q=80"
          alt="Color version of kittens in a basket looking around"
        />
      </wa-comparison>
    </template>
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-content {
    --min-column-size: 8rem;

    wa-lightbox-item > img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }

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

A video player works the same way. Set the type attribute to video to add the play button to its thumbnail.

The <wa-video> component requires Web Awesome Pro.
<wa-lightbox-item type="video" width="1920" height="1080">
  <img src="poster.jpg" alt="..." />
  <template>
    <wa-video poster="poster.jpg">
      <source src="video.mp4" type="video/mp4" />
    </wa-video>
  </template>
</wa-lightbox-item>

Single Image

Link to This Section

A lightbox with one item works as an image zoom. The counter, navigation buttons, and thumbnails are hidden when there's nothing to navigate.

Use a large, detailed image so there's something to see up close. Open this one and zoom in on the lavender.

The sun is setting over a lavender field
<wa-lightbox class="lightbox-single" label="Lavender field photo">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=3600&h=2400&fit=crop&q=80"
    caption="Sunset over a lavender field. Photo by Leonard Cotte on Unsplash."
    width="3600"
    height="2400"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-single img {
    width: 100%;
    max-width: 24rem;
    aspect-ratio: 3 / 2;
    border-radius: var(--wa-border-radius-m);
    object-fit: cover;
  }
</style>

Images in an Article

Link to This Section

A lightbox can wrap any content, and its items don't need to be next to each other or direct children. Wrap an article in a lightbox and each image in an item, and every image in the article opens in the same lightbox. Text, links, and everything else in between work as usual.

We set out early, while the valley floor was still in shadow and the cliffs were only starting to catch the light.

The sun shines on the mountains and trees
First light on the cliffs

By midday the trail had dropped down to the river, where the water was clear enough to count the stones on the bottom. The photos don't do it justice.

A river winding through an evergreen forest
The river below the trail
<wa-lightbox class="lightbox-article" label="Photos from the valley">
  <article>
    <p>
      We set out early, while the valley floor was still in shadow and the cliffs were only starting to catch the light.
    </p>

    <figure>
      <wa-lightbox-item
        src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
        width="1600"
        height="1067"
        caption="First light on the cliffs"
      >
        <img
          src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
          alt="The sun shines on the mountains and trees"
        />
      </wa-lightbox-item>
      <figcaption>First light on the cliffs</figcaption>
    </figure>

    <p>
      By midday the trail had dropped down to the river, where the water was clear enough to count the stones on the
      bottom. The <a href="https://unsplash.com/">photos</a> don't do it justice.
    </p>

    <figure>
      <wa-lightbox-item
        src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
        width="1600"
        height="1067"
        caption="The river below the trail"
      >
        <img
          src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
          alt="A river winding through an evergreen forest"
        />
      </wa-lightbox-item>
      <figcaption>The river below the trail</figcaption>
    </figure>
  </article>
</wa-lightbox>

<style>
  .lightbox-article {
    max-width: 32rem;

    figure {
      margin: var(--wa-space-l) 0;
    }

    img {
      width: 100%;
      border-radius: var(--wa-border-radius-m);
    }

    figcaption {
      margin-block-start: var(--wa-space-xs);
      color: var(--wa-color-text-quiet);
      font-size: var(--wa-font-size-s);
    }
  }
</style>

Items Without Thumbnails

Link to This Section

An item with nothing slotted in isn't shown on the page, but it still appears in the lightbox. Use this to show one image on the page and the rest in the lightbox. Set the thumbnail attribute to give the item an image for the thumbnail strip and a placeholder while it loads. Set the alt attribute too, since there's no thumbnail to take it from.

This example shows a cover photo with a button that opens the rest. The button uses declarative opening.

The sun shines on the mountains and trees View all 5 photos
<wa-lightbox id="lightbox-hidden" class="lightbox-hidden" label="Landscape photos" with-thumbnails>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    thumbnail="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
    alt="A river winding through an evergreen forest"
    width="1600"
    height="1067"
  ></wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    thumbnail="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
    alt="The sun is setting over a lavender field"
    width="1600"
    height="1067"
  ></wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=1600&h=1067&fit=crop&q=80"
    thumbnail="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=480&h=320&fit=crop&q=60"
    alt="A field of grass with the sun setting in the background"
    width="1600"
    height="1067"
  ></wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=1600&h=1067&fit=crop&q=80"
    thumbnail="https://images.unsplash.com/photo-1470071459604-3b5ec3a7fe05?w=480&h=320&fit=crop&q=60"
    alt="A scenic view of a mountain with clouds rolling in"
    width="1600"
    height="1067"
  ></wa-lightbox-item>

  <wa-button size="small" class="view-all" data-lightbox="open lightbox-hidden">
    <wa-icon slot="start" name="images"></wa-icon>
    View all 5 photos
  </wa-button>
</wa-lightbox>

<style>
  .lightbox-hidden {
    position: relative;
    max-width: 24rem;

    img {
      width: 100%;
      aspect-ratio: 3 / 2;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }

    .view-all {
      position: absolute;
      inset-block-end: var(--wa-space-s);
      inset-inline-end: var(--wa-space-s);
    }
  }
</style>

Customizing

Link to This Section

Combine custom properties and CSS parts to give a lightbox its own look. This example frosts the page behind the lightbox with the --backdrop-color and --backdrop-filter custom properties. The --controls-color and --controls-background custom properties set the color of the controls, counter, and caption, and the background the controls get when the media is behind them. CSS parts give the counter and the thumbnail strip the same see-through fill and a thin edge, and set smaller, bolder type for the counter and caption.

Use --show-duration and --hide-duration to set the animation speed, and --spacing, --slide-gap, and --thumbnail-size to adjust the layout.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field A field of grass with the sun setting in the background
<wa-lightbox class="wa-grid lightbox-styled" label="Landscape photos" with-thumbnails loop>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="First light in the valley"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="Where the river slows down"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="Lavender at golden hour"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
    caption="The last of the evening sun"
  >
    <img
      src="https://images.unsplash.com/photo-1475113548554-5a36f1f523d6?w=480&h=320&fit=crop&q=60"
      alt="A field of grass with the sun setting in the background"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-styled {
    --min-column-size: 8rem;
    --backdrop-color: color-mix(in oklab, var(--wa-color-surface-default) 30%, transparent);
    --backdrop-filter: blur(40px) saturate(180%);
    --controls-color: var(--wa-color-text-normal);
    --controls-background: color-mix(in oklab, var(--wa-color-surface-raised) 70%, transparent);
    --media-border-radius: var(--wa-border-radius-l);
    --thumbnail-size: 3rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-l);
      object-fit: cover;
    }

    &::part(counter),
    &::part(thumbnails) {
      border: solid 1px color-mix(in oklab, var(--controls-color) 12%, transparent);
      background: var(--controls-background);
      backdrop-filter: blur(20px) saturate(180%);
    }

    &::part(counter) {
      padding: var(--wa-space-2xs) var(--wa-space-s);
      border-radius: var(--wa-border-radius-pill);
      font-size: var(--wa-font-size-s);
      font-variant-numeric: tabular-nums;
      font-weight: var(--wa-font-weight-semibold);
    }

    &::part(caption) {
      font-size: var(--wa-font-size-s);
      font-weight: var(--wa-font-weight-semibold);
      letter-spacing: -0.01em;
    }

    &::part(thumbnails) {
      padding: var(--wa-space-xs);
      border-radius: calc(var(--wa-border-radius-m) + var(--wa-space-xs));
    }

    &::part(thumbnail) {
      border-radius: var(--wa-border-radius-m);
    }
  }
</style>

Opening & Closing Declaratively

Link to This Section

Add data-lightbox="open id" to any button on the page to open a lightbox without JavaScript, where id is the lightbox's ID. To open at a specific item, add the item's ID as well. Without one, the lightbox opens at the first item.

Add data-lightbox="close" to a button inside a lightbox to close it.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field Done
View all photos View the lavender field
<wa-lightbox id="lightbox-declarative" class="wa-grid lightbox-declarative" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    id="lightbox-declarative-lavender"
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>

  <wa-button slot="actions" data-lightbox="close">Done</wa-button>
</wa-lightbox>

<div class="wa-cluster">
  <wa-button data-lightbox="open lightbox-declarative">View all photos</wa-button>
  <wa-button data-lightbox="open lightbox-declarative lightbox-declarative-lavender">View the lavender field</wa-button>
</div>

<style>
  .lightbox-declarative {
    --min-column-size: 8rem;
    margin-block-end: var(--wa-space-m);

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

Opening Programmatically

Link to This Section

Set the index property to choose an item, then set the open property to true to show the lightbox. Set it to false to close the lightbox. The wa-item-change event is emitted whenever the current item changes.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field
Open the last photo
<wa-lightbox class="wa-grid lightbox-programmatic" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-programmatic {
    --min-column-size: 8rem;
    margin-block-end: var(--wa-space-m);

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

<div class="wa-cluster">
  <wa-button class="lightbox-programmatic-open">Open the last photo</wa-button>
  <span class="lightbox-programmatic-status"></span>
</div>

<script>
  const lightbox = document.querySelector('.lightbox-programmatic');
  const openButton = document.querySelector('.lightbox-programmatic-open');
  const status = document.querySelector('.lightbox-programmatic-status');

  openButton.addEventListener('click', () => {
    lightbox.index = lightbox.items.length - 1;
    lightbox.open = true;
  });

  lightbox.addEventListener('wa-item-change', event => {
    status.textContent = `Last viewed: photo ${event.detail.index + 1} of ${lightbox.items.length}`;
  });
</script>

Toolbar Actions

Link to This Section

The toolbar shows zoom and close buttons by default. Add your own buttons to the actions slot. Buttons in the slot are styled to match the lightbox's controls. The currentItem property gives you the item that's showing.

The sun shines on the mountains and trees A river winding through an evergreen forest The sun is setting over a lavender field
<wa-lightbox class="wa-grid lightbox-actions" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1499002238440-d264edd596ec?w=480&h=320&fit=crop&q=60"
      alt="The sun is setting over a lavender field"
    />
  </wa-lightbox-item>

  <wa-button slot="actions" class="open-original">
    <wa-icon name="arrow-up-right-from-square" label="Open original"></wa-icon>
  </wa-button>
</wa-lightbox>

<style>
  .lightbox-actions {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

<script>
  const lightbox = document.querySelector('.lightbox-actions');
  const openOriginal = lightbox.querySelector('.open-original');

  openOriginal.addEventListener('click', () => {
    window.open(lightbox.currentItem.src, '_blank', 'noopener');
  });
</script>

The lightbox styles slotted buttons by setting design tokens on them. To change one, set the token yourself. This gives a button the brand color while keeping its size and shape.

wa-button[slot='actions'] {
  --wa-color-fill-loud: var(--wa-color-brand-fill-loud);
  --wa-color-on-loud: var(--wa-color-brand-on-loud);
}

Preventing the Lightbox from Closing

Link to This Section

By default, the lightbox closes when the user clicks the close button or the backdrop, presses the Escape key, or pulls the image up or down. To keep it open, you can cancel the wa-hide event.

Check event.detail.source to see which element asked to close. This example keeps the lightbox open unless the close button is clicked.

Always leave a way to close the lightbox.
It covers the whole screen, so a handler that cancels every request leaves people stuck with no way back to the page.

The sun shines on the mountains and trees A river winding through an evergreen forest
<wa-lightbox class="wa-grid lightbox-prevent" label="Landscape photos">
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1426604966848-d7adac402bff?w=480&h=320&fit=crop&q=60"
      alt="The sun shines on the mountains and trees"
    />
  </wa-lightbox-item>
  <wa-lightbox-item
    src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=1600&h=1067&fit=crop&q=80"
    width="1600"
    height="1067"
  >
    <img
      src="https://images.unsplash.com/photo-1473448912268-2022ce9509d8?w=480&h=320&fit=crop&q=60"
      alt="A river winding through an evergreen forest"
    />
  </wa-lightbox-item>
</wa-lightbox>

<style>
  .lightbox-prevent {
    --min-column-size: 8rem;

    img {
      width: 100%;
      aspect-ratio: 1;
      border-radius: var(--wa-border-radius-m);
      object-fit: cover;
    }
  }
</style>

<script>
  const lightbox = document.querySelector('.lightbox-prevent');

  // Only close from the close button
  lightbox.addEventListener('wa-hide', event => {
    if (event.target === lightbox && !event.detail.source.part.contains('close-button')) {
      event.preventDefault();
    }
  });
</script>

Accessibility Considerations

Link to This Section

The lightbox handles most accessibility needs for you.

  • Focus. Focus is kept inside the lightbox while it's open and returns to the current item's thumbnail when it closes. If that item has no thumbnail, focus returns to whatever opened the lightbox.
  • Announcements. The current item's position, alternative text, and caption are announced as you move between items.
  • Zooming without gestures. Clicking the image, double-tapping it, and the zoom button do everything that pinching does.
  • Reduced motion. When the user prefers reduced motion, the lightbox opens and closes without animating and switches items without scrolling.

The lightbox can be used entirely from the keyboard.

Key Action
← / → Show the previous or next item, or pan the image when it's zoomed.
↑ / ↓ Pan the image when it's zoomed.
Home / End Show the first or last item.
+ / - Zoom in or out.
0 Reset the zoom.
Escape Close the lightbox.

A few things are up to you.

  • Give every thumbnail meaningful alt text. The lightbox reuses it for the full-size image unless you set the alt attribute on the item.
  • Set the label attribute to describe what the lightbox contains.
  • Captions are shown as plain text. Don't rely on them to carry information that isn't also in the alternative text.

API

Link to This Section

Importing

Link to This Section

If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.

CDN npm Self-Hosted React

Import this component directly from the CDN:

import 'https://ka-f.webawesome.com/[email protected]/components/lightbox/lightbox.js';

After installing Web Awesome via npm, import this component:

import '@awesome.me/webawesome/dist/components/lightbox/lightbox.js';

If you're self-hosting Web Awesome, import this component from your server:

import './webawesome/dist/components/lightbox/lightbox.js';

To import this component for React 18 or below, use the following code:

import WaLightbox from '@awesome.me/webawesome/dist/react/lightbox/index.js';

Slots

Link to This Section

Learn more about using slots.

Name Description
(default) One or more <wa-lightbox-item> elements, along with any markup you need to lay them out.
actions Extra buttons to show in the lightbox's toolbar, such as download or share. Works best with <wa-button>, which is styled to match the built-in controls.
close-icon Optional close icon to use instead of the default. Works best with <wa-icon>.
next-icon Optional next icon to use instead of the default. Works best with <wa-icon>.
previous-icon Optional previous icon to use instead of the default. Works best with <wa-icon>.
zoom-in-icon Optional icon to show on the zoom button when the image can be zoomed in. Works best with <wa-icon>.
zoom-out-icon Optional icon to show on the zoom button when the image is zoomed in. Works best with <wa-icon>.

Attributes & Properties

Link to This Section

Learn more about attributes and properties.

Name Description Reflects
currentItem
The current item. Useful for download and share buttons in the actions slot.
Type WaLightboxItem | undefined
index
index
The zero-based index of the current item. Set this before opening to choose which item the lightbox starts on.
Type number
Default 0
items
The lightbox's items, in document order.
Type WaLightboxItem[]
label
label
A label that describes the lightbox to assistive devices, e.g. "Vacation photos".
Type string
Default ''
loop
loop
Wraps around when navigating past the first or last item with the buttons or the keyboard.
Type boolean
Default false
open
open
Indicates whether or not the lightbox is open. Toggle this attribute to show and hide the lightbox.
Type boolean
Default false
withoutCounter
without-counter
Hides the counter that shows the current item's position.
Type boolean
Default false
withoutNavigation
without-navigation
Hides the previous and next buttons. Swiping and the arrow keys still work. The buttons are always hidden on touch screens, where swiping takes their place.
Type boolean
Default false
withoutZoom
without-zoom
Disables zooming and removes the zoom button.
Type boolean
Default false
withThumbnails
with-thumbnails
Shows a strip of thumbnails for jumping between items.
Type boolean
Default false

Methods

Link to This Section

Learn more about methods.

Name Description Arguments
next() Shows the next item.
previous() Shows the previous item.
zoomIn() Zooms in on the current image.
zoomOut() Zooms out of the current image.

Events

Link to This Section

Learn more about events.

Name Description
wa-after-hide Emitted after the lightbox closes and all animations are complete.
wa-after-show Emitted after the lightbox opens and all animations are complete.
wa-hide Emitted when the lightbox is requested to close. Calling event.preventDefault() will prevent the lightbox from closing. You can inspect event.detail.source to see which element caused the lightbox to close. If the source is the lightbox's internal dialog, the user has pressed Escape, clicked the backdrop, pulled the media up or down, or the lightbox has been closed programmatically.
wa-item-change Emitted when the current item changes.
wa-show Emitted when the lightbox opens. Calling event.preventDefault() will prevent it from opening.

CSS Custom Properties

Link to This Section

Learn more about CSS custom properties.

Name Description
--backdrop-color
The color of the backdrop.
Default var(--wa-color-overlay-media)
--backdrop-filter
A filter to apply to the backdrop behind the lightbox.
Default blur(1rem)
--controls-background
The background of the controls when the media is behind them.
Default rgb(0 0 0 / 0.5)
--controls-color
The text and icon color used for the controls, counter, and caption.
Default var(--wa-color-neutral-95)
--hide-duration
The animation duration when hiding the lightbox.
Default var(--wa-transition-slow)
--media-border-radius
The border radius of the media in each slide.
Default 0px
--show-duration
The animation duration when showing the lightbox.
Default var(--wa-transition-slow)
--slide-gap
The space between slides.
Default var(--wa-space-xl)
--spacing
The space around the media, the caption, and the lightbox's controls. Grows with the viewport by default.
Default clamp(var(--wa-space-m), 3vw, var(--wa-space-2xl))
--thumbnail-size
The size of each thumbnail in the strip.
Default 3.5rem

Custom States

Link to This Section

Learn more about custom states.

Name Description CSS selector
open Applied when the lightbox is open. :state(open)
zoomed Applied when the current image is zoomed in. :state(zoomed)

CSS Parts

Link to This Section

Learn more about CSS parts.

Name Description CSS selector
backdrop The backdrop behind the media. ::part(backdrop)
caption The current item's caption. ::part(caption)
close-button The close button. ::part(close-button)
counter The "3 of 12" counter. ::part(counter)
dialog The lightbox's internal <dialog> element. ::part(dialog)
image The full-size image in a slide. ::part(image)
navigation-button The previous and next buttons. ::part(navigation-button)
navigation-button-next Applied to the next button. ::part(navigation-button-next)
navigation-button-previous Applied to the previous button. ::part(navigation-button-previous)
scroll-container The scroll container that holds the slides. ::part(scroll-container)
slide A slide. ::part(slide)
thumbnail A thumbnail in the strip. ::part(thumbnail)
thumbnail-active Applied to the current item's thumbnail. ::part(thumbnail-active)
thumbnails The thumbnail strip. ::part(thumbnails)
toolbar The toolbar at the top of the lightbox. ::part(toolbar)
video The video in a slide. ::part(video)
zoom-button The button that zooms the current image in and out. ::part(zoom-button)

Dependencies

Link to This Section

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

  • <wa-icon>
  • <wa-lightbox-item>
Need a hand? Report a bug Ask for help
Go Make Something Awesome
Version 3.15.0 © Fonticons, Inc.
  • Terms
  • Privacy
  • Refunds
  • Core License
  • Pro License

Quick Links

  • Components
  • CSS Utilities
  • Theming
  • Using with AI
  • Changelog
  • Help & Support

Recent Searches

    D'oh! No results for “”

    Suggest on GitHub Ask on Discord
    Navigate Select
    Close Esc

    We Have Cookies…

    We use cookies to make webawesome.com work better by storing limited information about your usage.

    We value your privacy, so we won't use them for evil or ask you to join the dark side.

    Customize
    Necessary Only Accept All
    Strictly Necessary
    Required to make the site function correctly — cannot be turned off
    Functionality Analytics
    Cancel Confirm Cookie Choices