Description Allows for a “image lightbox” or similar experience where upon user interaction, an image expands to fill the viewport until it is closed again by the user.
Availability Stable
Required Script <script async custom-element="amp-image-lightbox" src="https://cdn.ampproject.org/v0/amp-image-lightbox-0.1.js"></script>
Supported Layouts nodisplay
Examples Annotated code example for amp-image-lightbox

Behavior

The typical scenario looks like this:

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

The amp-image-lightbox is activated using on action on the amp-img element by referencing the lightbox element's ID. When activated, it places the image in the center of the full-viewport lightbox. Notice that any number of images in the article can use the same amp-image-lightbox. The amp-image-lightbox element itself must be empty and have layout=nodisplay set.

The amp-image-lightbox also can optionally display a caption for the image at the bottom of the viewport. The caption is discovered as following:

  1. The contents of the <figcaption> element when image is in the figure tag.
  2. The contents of the element whose ID is specified by the image's aria-describedby attribute.

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

Styling

The amp-image-lightbox component can be styled 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:

Action Description
(default) Opens the image lightbox with the source image being the one that triggered the action.

Examples

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

Attributes

layout

Must be set to nodisplay.

Validation

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