Bento

Bento Lightbox Gallery

<head>

    <script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <!-- These styles prevent Cumulative Layout Shift on the unupgraded custom element -->
    <link
      rel="stylesheet"
      href="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.css"
    />
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.js"
    ></script>
    <style>
      .body {
        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto,
          Helvetica, Arial, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji',
          'Segoe UI Symbol';
        background: #ecf1f3;
      }
      .image-grid {
        display: grid;
        grid-template-columns: 50vw 50vw;
        grid-gap: 10px;
        margin: 2rem 0;
      }
    </style>
</head>

<body>

    <bento-lightbox-gallery></bento-lightbox-gallery>
    <section class="image-grid">
      <figure>
        <img
          width="160"
          height="120"
          src="https://picsum.photos/id/237/640/480"
          lightbox
        />
        <figcaption>A random image</figcaption>
      </figure>
      <figure>
        <img
          width="160"
          height="120"
          src="https://picsum.photos/id/238/640/480"
          lightbox
        />
        <figcaption>Another random image</figcaption>
      </figure>
      <figure>
        <img
          width="160"
          height="120"
          src="https://picsum.photos/id/239/640/480"
          lightbox
        />
        <figcaption>And another random image</figcaption>
      </figure>
      <figure>
        <img
          width="160"
          height="120"
          src="https://picsum.photos/id/240/640/480"
          lightbox
        />
        <figcaption>Aaaand another random image</figcaption>
      </figure>
    </section>
</body>

Provides a modal "lightbox" experience for images.

When the user interacts with the element, a modal expands to fill the viewport until it is closed by the user.

Use bento-lightbox-gallery as a web component or a React functional component:

↓ Web Component ↓ React / Preact

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

Import via npm

npm install @bentoproject/lightbox-gallery
import {defineElement as defineBentoLightboxGallery} from '@bentoproject/lightbox-gallery';
defineBentoLightboxGallery();

Import via <script>

<script type="module" async src="https://cdn.ampproject.org/bento.mjs"></script>
<script nomodule src="https://cdn.ampproject.org/bento.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.css"
>

<script type="module" async src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.mjs"></script>
<script nomodule async src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.js"></script>

Example

<head>

<script
      type="module"
      async
      src="https://cdn.ampproject.org/bento.mjs"
    ></script>
    <script nomodule src="https://cdn.ampproject.org/bento.js"></script>
    <link
      rel="stylesheet"
      type="text/css"
      href="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.css"
    />
    <script
      type="module"
      async
      src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.mjs"
    ></script>
    <script
      nomodule
      async
      src="https://cdn.ampproject.org/v0/bento-lightbox-gallery-1.0.js"
    ></script>
</head>

<body>

<bento-lightbox-gallery></bento-lightbox-gallery>
    <figure>
      <img id="my-img" src="img1.jpwg" lightbox />
      <figcaption>dog wearing yellow shirt.</figcaption>
    </figure>
    <figure>
      <img src="img2.jpeg" lightbox/>
    </figure>
    <figure>
      <img src="img2.jpeg" lightbox/>
    </figure>
</body>

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"
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"
alt="picture of cn tower"
/>

Interactivity and API usage

Bento components 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();

You can open a specific lightbox gallery group to a specific slide by passing in extra arguments:

api.open(1, 'toronto') // opens gallery with images in the "toronto" group to the 2nd image
api.open(null, 'toronto') // opens gallery with images in the "toronto" group to the 1st image

Attributes

Set lightbox attribute to an id to assign different images to different groups. For example, in the example below, clicking any of the group1 images will only show img1.jpeg, img3.jpeg, and img5.jpeg and clicking any of the group2 images will only show img2.jpeg, img4.jpeg, img6.jpeg

<img src="img1.jpeg" lightbox="group1">
<img src="img2.jpeg" lightbox="group2">
<img src="img3.jpeg" lightbox="group1">
<img src="img4.jpeg" lightbox="group2">
<img src="img5.jpeg" lightbox="group1">
<img src="img6.jpeg" lightbox="group2">

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.

Import via npm

npm install @bentoproject/lightbox-gallery
import React from 'react';
import {
BentoLightboxGalleryProvider,
WithBentoLightboxGallery,
} from '@bentoproject/lightbox-gallery/react';

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

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.

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

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

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.

More details