search

benhowell / react-grid-gallery

Justified image gallery component for React
https://benhowell.github.io/react-grid-gallery/
MIT License
1.01k stars 209 forks source link
gallery images javascript justified lightbox photo-gallery photos react selectable tagging tags thumbnails

readme

React Grid Gallery

Justified image gallery component for React inspired by Google Photos.

:tada: v1.0.0 is out!

There are breaking changes with v0.5.x, check out the migration guide to learn more. Documentation for v0.5.x is here.

Live Demo & Examples

https://benhowell.github.io/react-grid-gallery/

Installation

Using npm:

npm install --save react-grid-gallery

Quick Start

import { Gallery } from "react-grid-gallery";

const images = [
   {
      src: "https://c2.staticflickr.com/9/8817/28973449265_07e3aa5d2e_b.jpg",
      width: 320,
      height: 174,
      isSelected: true,
      caption: "After Rain (Jeshu John - designerspics.com)",
   },
   {
      src: "https://c2.staticflickr.com/9/8356/28897120681_3b2c0f43e0_b.jpg",
      width: 320,
      height: 212,
      tags: [
         { value: "Ocean", title: "Ocean" },
         { value: "People", title: "People" },
      ],
      alt: "Boats (Jeshu John - designerspics.com)",
   },
   {
      src: "https://c4.staticflickr.com/9/8887/28897124891_98c4fdd82b_b.jpg",
      width: 320,
      height: 212,
   },
];

<Gallery images={images} />

Image Options

Property Type Description
src string Required. A string referring to any valid image resource (file, url, etc).
width number Required. Width of the image.
height number Required. Height of the image.
nano string:base64 Optional. Thumbnail Base64 image will be injected to background under the main image. This provides a base64, 4x4 generated image whilst the image is being loaded.
alt string Optional. Image alt attribute.
tags array Optional. An array of objects containing tag attributes (value, title and key if value is element). e.g. {value: "foo", title: "bar"} or {value: <a href={tag.url}>{tag.name}</a>, title: tag.title, key: tag.key}
isSelected bool Optional. The selected state of the image.
caption string | ReactNode Optional. Image caption.
customOverlay element Optional. A custom element to be rendered as a thumbnail overlay on hover.
thumbnailCaption string | ReactNode Optional. A thumbnail caption shown below thumbnail.
orientation number Optional. Orientation of the image. Many newer digital cameras (both dSLR and Point & Shoot digicams) have a built-in orientation sensor. The output of this sensor is used to set the EXIF orientation flag in the image file's metatdata to reflect the positioning of the camera with respect to the ground (See EXIF Orientation Page for more info).

Gallery Options

Property Type Description
images array Required. An array of objects containing image properties (see Image Options above).
id string Optional, default ReactGridGallery. id attribute for <Gallery> tag. This prop may be useful for those who wish to discriminate between multiple galleries.
enableImageSelection bool Optional, default true. Allow images to be selectable. Setting this option to false whilst supplying images with isSelected: true will result in those images being permanently selected.
onSelect func Optional. Function to execute when an image is selected. Optional args: index (index of selected image in images array), image (the selected image), event. This function is only executable when enableImageSelection: true.
rowHeight number Optional, default 180. The height of each row in the gallery.
maxRows number Optional. The maximum number of rows to show in the gallery.
margin number Optional, default 2. The margin around each image in the gallery.
onClick func Optional. Function to execute when gallery image clicked. Optional args: index (index of selected image in images array), image (the clicked image), event (the click event).
tagStyle func | CSSProperties Optional. Style or function that returns style to pass to tag elements. Optional args: item (the image item in images). Overrides internal tag style.
tileViewportStyle func | CSSProperties Optional. Style or function to style the image tile viewport. Optional args: item (the image item in images). Overrides internal tileViewportStyle function.
thumbnailStyle func | CSSProperties Optional. Style or function to style the image thumbnail. Optional args: item (the image item in images). Overrides internal thumbnailStyle function.
thumbnailImageComponent React component Optional. Substitute in a React component that would get passed imageProps (the props that would have been passed to the <img> tag) and item (the original item in images) to be used to render thumbnails; useful for lazy loading.
defaultContainerWidth number Optional. Set default width for the container. This option is useful during server-side rendering when we want to generate an initial markup before we can detect the actual container width.

General Notes

Contributing

All contributions to react-grid-gallery are very welcome. Feature requests, issue reports and pull requests are greatly appreciated. Please follow the contribution guidelines

License

React Grid Gallery is free to use for personal and commercial projects under the MIT License. Attribution is not required, but appreciated.

Acknowledgements