amp-image-lightbox

Behavior

The amp-image-lightbox component provides a lightbox experience for a specified image. When the user clicks the image, the image displays in the center of a full-viewport lightbox.

Typical usage

The following is a typical example using an amp-image-lightbox:

<amp-image-lightbox id="lightbox1" layout="nodisplay"></amp-image-lightbox>
<amp-img
  on="tap:lightbox1"
  role="button"
  tabindex="0"
  src="image1.jpg"
  width="200"
  height="100"
></amp-img>

When the user clicks the image, the <amp-img> activates the <amp-image-lightbox> via the on action, which references the ID of the <amp-image-lightbox> element (i.e., lightbox1). The <amp-image-lightbox> then displays the image in the center of the full-viewport lightbox. Note that the amp-image-lightbox element itself must be empty and must be set to layout=nodisplay.

Among other things the amp-image-lightbox allows the following user manipulations: zooming, panning, showing/hiding of the description. Pressing the escape key on a keyboard closes the lightbox.

Using a single lightbox for multiple images

You can use the same amp-image-lightbox for more than one image on the AMP page.

In this example, two images display: a cat and a frog. When the user clicks either image, the image displays in the lightbox.

<amp-image-lightbox id="lightbox1" layout="nodisplay"></amp-image-lightbox>

<amp-img
  on="tap:lightbox1"
  role="button"
  tabindex="0"
  src="/img/frog.jpg"
  layout="responsive"
  width="360"
  height="360"
></amp-img>

<amp-img
  on="tap:lightbox1"
  role="button"
  tabindex="0"
  src="/img/cat.jpg"
  layout="responsive"
  width="360"
  height="360"
></amp-img>

Captions

Optionally, you can display captions at the bottom of the viewport for the image. The <amp-image-lightbox> components determines the content for the caption as follows:

1. If the image is in a figure tag, the content of the <figcaption> displays for the caption.
2. If the image specifies an aria-describedby attribute, the content of the element whose ID is specified by the aria-describedbyattribute displays for the caption.

Examples: Using captions

<!-- Captions via figcaption -->
<figure>
  <amp-img
    on="tap:lightbox1"
    role="button"
    tabindex="0"
    src="dog.jpg"
    layout="responsive"
    width="300"
    height="246"
  ></amp-img>
  <figcaption>Border Collie</figcaption>
</figure>

<!-- Captions via aria-describedby -->
<div>
  <amp-img
    on="tap:lightbox1"
    role="button"
    tabindex="0"
    src="dog.jpg"
    aria-describedby="imageDescription"
    layout="responsive"
    width="300"
    height="246"
  ></amp-img>
  <div id="imageDescription">This is a border collie.</div>
</div>

Attributes

<amp-image-lightbox
  id="image-lightbox1"
  layout="nodisplay"
  data-close-button-aria-label="Close"
></amp-image-lightbox>

Styling

You can style the amp-image-lightbox component with standard CSS. Some of the properties that can be styled are background and color. The amp-image-lightbox-caption class is also available to style the caption section.

Actions

The amp-image-lightbox exposes the following actions you can use AMP on-syntax to trigger:

Validation

See amp-image-lightbox rules in the AMP validator specification.