Displays elements in a full-viewport “lightbox” modal.
<script async custom-element="amp-lightbox" src="https://cdn.ampproject.org/v0/amp-lightbox-0.1.js"></script>
amp-lightbox component defines child elements that display in a
full-viewport overlay/modal. When the user taps or clicks an element (e.g., a
amp-lightbox ID referenced in the clicked element's
attribute triggers the lightbox to take up the full viewport and displays the
child elements of the
There are some differences between using
amp-lightbox in normal AMP documents
vs. ads written in AMPHTML.
For AMPHTML ads, the
close-button attribute is required. This attribute causes
a header to render at the top of your lightbox. The header contains a close
button and a label that displays "Ad". Requirement of this header is needed to:
- Set a consistent and predictable user experience for AMPHTML ads.
- Ensure that an exit point for the lightbox always exists, otherwise the creative could effectively hijack the host document content via a lightbox.
close-button attribute is required and only allowed in AMPHTML ads. In
regular AMP documents, you can render a close button wherever you need it as
part of the
Scrollable lightboxes are disallowed
For AMPHTML ads, scrollable lightboxes are not allowed.
When you use
<amp-lightbox> in AMPHTML ads, the background of your
element becomes transparent because the AMP runtime resizes and realigns your
creative's content before the lightbox is expanded. This is done to prevent a
visual "jump" of the creative while the lightbox opens. If your creative needs a
background, set it on an intermediate container (like a full-size
instead of the
When the AMPHTML ad is running in a third-party environment (for example, in a non-AMP document), the creative is centered relative to the viewport and is then expanded. This is because third-party iframes need to rely on a postMessage API to enable features like frame resizing, which is asynchronous, so centering the creative first allows a smooth transition without visual jumps.
Examples of transitions in lightboxes for AMPHTML ads
In the examples below, we demonstrate how the transition looks for an AMPHTML ad
that has the
animate-in="fly-in-bottom" attribute set on the lightbox element
for an AMPHTML ad in a friendly iframe, and an AMPHTML ad in a third-party
On friendly iframes (e.g., coming from an AMP cache)
On third-party iframes (e.g., outside the AMP cache)
A unique identifier for the lightbox.
Must be set to
Renders a close button header at the top of the lightbox. This attribute is required for use with AMPHTML Ads. It is invalid on other AMP formats.
Defines the style of animation for opening the lightbox. By default, this will
be set to
fade-in. Valid values are
fly-in-bottom animation presets modify the
property of the
amp-lightbox element. Do not rely on transforming the
amp-lightbox element directly. If you need to apply a transform, set it on a
nested element instead.
Opens the lightbox.
Closes the lightbox.
You can style the
amp-lightbox with standard CSS.
Pressing the escape key on the keyboard or setting focus on an element outside
the lightbox closes the lightbox. Alternatively, setting the
on attribute on
one or more elements within the lightbox and setting its method to
closes the lightbox when the element is tapped or clicked. Once closed, the
focus will be sent back to the trigger element.
For accessibility reasons, if the user does not provide a focus in the lightbox
on open (using
autofocus attribute or forcing focus on open), the focus will
be set on the first element using
on:tap. Otherwise, a close button only
visible to screen readers, optionally using
attribute value, will be created and focused on.
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