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 / PreactWeb 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
lightbox
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.