AMP

Important: this documentation is not applicable to your currently selected format stories!

amp-lightbox

Displays elements in a full-viewport “lightbox” modal.

Required Scripts

<script async custom-element="amp-lightbox" src="https://cdn.ampproject.org/v0/amp-lightbox-0.1.js"></script>

Supported Layouts

Behavior

The 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 button), the amp-lightbox ID referenced in the clicked element's on attribute triggers the lightbox to take up the full viewport and displays the child elements of the amp-lightbox.

Pressing the escape key on the keyboard closes the lightbox. Alternatively, setting the on attribute on one or more elements within the lightbox and setting its method to close closes the lightbox when the element is tapped or clicked.

<button on="tap:quote-lb">See Quote</button>
<amp-lightbox id="quote-lb" layout="nodisplay">
  <blockquote>
    "Don't talk to me about JavaScript fatigue" - Horse JS
  </blockquote>
  <button on="tap:quote-lb.close">Nice!</button>
</amp-lightbox>

For showing images in a lightbox, there's also the <amp-image-lightbox> component.

Attributes

animate-in (optional)

Defines the style of animation for opening the lightbox. By default, this will be set to fade-in. Valid values are fade-in, fly-in-bottom and fly-in-top.

The fly-in-top and fly-in-bottom animation presets modify the transform 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.

id (required)

A unique identifer for the lightbox.

layout (required)

Must be set to nodisplay.

scrollable (optional)

When the scrollable attribute is present, the content of the lightbox can scroll when overflowing the height of the lightbox.

Styling

You can style the amp-lightbox with standard CSS.

Actions

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

Action Description
open (default) Opens the lightbox.
close Closes the lightbox.

Scrollable lightboxes are disallowed

For AMPHTML ads, scrollable lightboxes are not allowed.

Transparent background

When you use <amp-lightbox> in AMPHTML ads, the background of your <body> 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 <div>) instead of the <body>.

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 lightbox 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 iframe.

On friendly iframes (e.g., coming from an AMP cache)

On third-party iframes (e.g., outside the AMP cache)

Validation

See amp-lightbox rules in the AMP validator specification.

Need more help?

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