The Bento Lightbox Gallery component provides a "lightbox" experience for other components (e.g., HTML images, Bento carousel). When the user interacts with the element, a UI component expands to fill the viewport until it is closed by the user. Currently, only images are supported.

Use Bento Lightbox Gallery as a web component <bento-lightbox-gallery>, or a Preact/React functional component <BentoLightboxGallery>.

Web Component

You must include each Bento component's required CSS library to guarantee proper loading and before adding custom styles. As a web component

The examples below demonstrate use of the <bento-lightbox-gallery> web component.

Example: Import via npm

[example preview="top-frame" playground="false"]

Install via npm:

npm install @ampproject/bento-lightbox-gallery

import '@ampproject/bento-lightbox-gallery';

[/example]

Example: Import via `<script>`

[example preview="top-frame" playground="false"]

<head>
    <script src="https://cdn.ampproject.org/custom-elements-polyfill.js"></script>
    <!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
    <style data-bento-boilerplate>
      bento-lightbox-gallery[hidden] {
        display: none !important;
      }
    </style>
    <script async src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.js"></script>
  </head>

  <figure>
     <img
       id="my-img"
       width="360"
       height="240"
       src="https://images.unsplash.com/photo-1583511655857-d19b40a7a54e?ixlib=rb-1.2.1&ixid=eyJhcHBfaWQiOjEyMDd9&auto=format&fit=crop&w=1498&q=80"
       lightbox
     />
     <figcaption>dog wearing yellow shirt.</figcaption>
    </figure>
  <div class="buttons" style="margin-top: 8px;">
    <button id="change-img">
      change image
    </button>
  </div>

  <script>
    (async () => {
      const img = document.queryselector('#my-img');
      await customelements.whendefined('img');
      // set up button actions
      document.queryselector('#change-img').onclick = () => {
        img.setattribute('src', 'https://images.unsplash.com/photo-1603123853880-a92fafb7809f?ixlib=rb-1.2.1&auto=format&fit=crop&w=1498&q=80')
      }
    })();
  </script>

[/example]

Usage

To use bento-liightbox-gallery, ensure the required script is included in your <head> section, then add the lightbox attribute on an <img> or <bento-carousel> element.

Add Captions

Optionally, you can specify a caption for each element in the lightbox. these fields are automatically read and displayed by the <bento-lightbox-gallery> in the following order of priority:

figcaption (if the lightboxed element is the child of a figure)
aria-describedby
alt
aria-label
aria-labelledby

In the following example, <bento-lightbox-gallery> displays the figcaption value as its description, showing "toront's cn tower was ....".

<figure>
  <img
    id="hero-img"
    lightbox="toronto"
    src="https://picsum.photos/1600/900?image=1075"
    layout="responsive"
    width="1600"
    height="900"
    alt="picture of cn tower."
  >
  <figcaption class="image">
    toronto's cn tower was built in 1976 and was the tallest free-standing
    structure until 2007.
  </figcaption>
</figure>

In the following example, <bento-lightbox-gallery> displays the alt value as its description, showing "picture of cn tower".

<img
  id="hero-img"
  lightbox="toronto"
  src="https://picsum.photos/1600/900?image=1075"
  layout="responsive"
  width="1600"
  height="900"
  alt="picture of cn tower"
>

Interactivity and API usage

Bento enabled components used as a standalone web component are highly interactive through their API. The bento-lightbox-gallery component API is accessible by including the following script tag in your document:

await customElements.whenDefined('bento-lightbox-gallery');
const api = await lightboxGallery.getApi();

Actions

The bento-lightbox-gallery API allows you to perform the following action:

`open`

Opens the lightbox gallery.

api.open();

Layout And Style

Each bento component has a small css library you must include to guarantee proper loading without content shifts. Because of order-based specificity, you must manually ensure that stylesheets are included before any custom styles.

<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.css">

Preact/React Component

The preact/react version of the bentolightboxgallery functions differently than the web component version. The following example will demonstrate the use of <BentoLightboxGallery> as a functional component.

Example: Import Via npm

[example preview="top-frame" playground="false"]

npm install @ampproject/bento-lightbox-gallery

import React from 'react';
import {
  BentoLightboxGalleryProvider,,
  WithBentoLightboxGallery,
} from '@ampproject/bento-lightbox-gallery/react';

function App() {
  return (
      <BentoLightboxGalleryProvider>
        <WithBentoLightboxGallery>
          <img src="https://images.unsplash.com/photo-1562907550-096d3bf9b25c"/>
        </WithBentoLightboxGallery>
      </BentoLightboxGalleryProvider>
  );
}

[/example]

Example Using BentoBaseCarousel

<BentoLightboxGallery> can be used with a <BentoBaseCarousel> child in order to lightbox all of the carousel's children. As you navigate throught the carousel items in the lightbox, the original carousel slides are synchronised so that when the lightbox is closed, the user ends up on the same slide as they were originally on.

[example preview="top-frame" playground="false"]

import React from 'react';
import {BentoBaseCarousel} from '../../../amp-base-carousel/1.0/component';
import {
  BentoLightboxGalleryProvider,,
  WithBentoLightboxGallery,
} from '@ampproject/bento-lightbox-gallery/react';

function App() {
  return (
       <BentoLightboxGalleryProvider>
        <BentoBaseCarousel lightbox style={{width: '240px', height: '160px'}}>
          <img
            src="https://images.unsplash.com/photo-1562907550-096d3bf9b25c"
            thumbnailSrc="https://images.unsplash.com/photo-1562907550-096d3bf9b25c"
          />
        </BentoBaseCarousel>
      </BentoLightboxGalleryProvider>
  );
}

[/example]

For further examples of how to use the BentoLightboxGallery please check the storybook example found in (Basic.js)[./storybook/Basic.js].

Props for BentoLightboxGalleryProvider

onBeforeOpen

A prop which takes a function which is executed before the lightbox is opened.

onAfterOpen

A prop which takes a function which is executed after the lightbox is opened.

onAfterClose

A prop which takes a function which is executed after the lightbox is closed.

onViewGrid

A prop which takes a function which is executed when the user enters the grid view.

onToggleCaption

A prop which takes a function which is executed when the captions are toggled.

Props for WithBentoLightboxGallery

enableActivation

A boolean prop which defaults to true which lets the child image activate the lightbox experience.

onClick

A prop which takes a functhion which is executed when the image is clicked.

FAQs

Package last updated on 14 Oct 2021

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@ampproject/amp-lightbox-gallery

Bento Lightbox Gallery

Usage

Web Component

Example: Import via npm

Example: Import via <script>

Usage

Add Captions

Interactivity and API usage

Actions

open

Layout And Style

Preact/React Component

Example: Import Via npm

Example Using BentoBaseCarousel

Props for BentoLightboxGalleryProvider

onBeforeOpen

onAfterOpen

onAfterClose

onViewGrid

onToggleCaption

Props for WithBentoLightboxGallery

enableActivation

onClick

Related posts

Two Malicious Rust Crates Impersonate Popular Logger to Steal Wallet Keys

Malicious fezbox npm Package Steals Browser Passwords from Cookies via Innovative QR Code Steganographic Technique

Example: Import via `<script>`

`open`