Table of contents

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

amp-lightbox

You can now use this component outside valid AMP documents using the Bento version of this component. Learn more in the Bento guide.

Description

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

nodisplay

Usage

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.

For showing images in a lightbox, there's also the <amp-image-lightbox> component. To show a gallery of images in a lightbox, you can use <amp-lightbox-gallery>.

Attributes

`id`

A unique identifier for the lightbox.

`layout`

Must be set to nodisplay.

`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.

`data-close-button-aria-label` (optional)

Optional attribute used to set ARIA label for the autogenerated close button added for accessibility. By default the applied label is "Close the modal".

`scrollable` (optional)

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

Actions

`open` (default)

Opens the lightbox.

`close`

Closes the lightbox.

Styling

You can style the amp-lightbox with standard CSS.

Accessibility

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 close 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 data-close-button-aria-label attribute value, will be created and focused on.

<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>

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

amp-lightbox 1.0 0.1