amp-image-lightbox
Provides a lightbox effect for a specified image.
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 | See AMP By Example's amp-image-lightbox sample. |
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:
- If the image is in a
figure
tag, the content of the<figcaption>
displays for the caption. - If the image specifies an
aria-describedby
attribute, the content of the element whose ID is specified by thearia-describedby
attribute 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
layout (required) | Must be set to nodisplay . |
id (required) | The ID for the lightbox element that's used as a target for the image's on action. |
data-close-button-aria-label (optional) | An ARIA label that you can use for a close button. |
<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:
Action | Description |
---|---|
open (default) | Opens the image lightbox with the source image being the one that triggered the action. |
Validation
See amp-image-lightbox rules in the AMP validator specification.
You've read this document a dozen times but it doesn't really cover all of your questions? Maybe other people felt the same: reach out to them on Stack Overflow.
Go to Stack Overflow Found a bug or missing a feature?The AMP project strongly encourages your participation and contributions! We hope you'll become an ongoing participant in our open source community but we also welcome one-off contributions for the issues you're particularly passionate about.
Go to GitHub