Skip to content

browniebroke/gatsby-image-gallery

Repository files navigation

gatsby-image-gallery

CI status Current npm package version. Released under the MIT license.

Very basic gallery grid based on gatsby-plugin-image and react-image-lightbox, styling powered by styled-components.

Install

npm install --save @browniebroke/gatsby-image-gallery

Compatibility

Please check the table below to choose the version of this library to use depending on your version of Gatsby:

Gatsby Image Gallery Gatsby Gatsby Plugin Image Gatsby Image
v5 v2 Not supported v3
v6 v3 v1 Not supported
v7 v4-v5 v2-v3 Not supported
v8 v5 v3 Not supported

Only the latest major version of Gatsby Image Gallery is supported.

Usage

This library provides a Gallery component, rendering as a grid of images that can be clicked to open in full size inside a lightbox. See below for a minimal example:

import { graphql } from 'gatsby'
import React from 'react'

import Gallery from '@browniebroke/gatsby-image-gallery'

const MyPage = ({ data }) => {
  const images = data.allFile.edges.map(({ node }) => node.childImageSharp)
  // `images` is an array of objects with `thumb` and `full`
  return <Gallery images={images} />
}

export const pageQuery = graphql`
  query ImagesForGallery {
    allFile {
      edges {
        node {
          childImageSharp {
            thumb: gatsbyImageData(
              width: 270
              height: 270
              placeholder: BLURRED
            )
            full: gatsbyImageData(layout: FULL_WIDTH)
          }
        }
      }
    }
  }
`

export default MyPage

The images prop

The images prop is an array of objects with 2 required properties: thumb and full that should each be a GatsbyImage compatible object.

In addition, images may have the following properties:

  • thumbAlt: (string) used to set the alt attribute on the thumbnail image
  • title: (node) passed to the Lightbox component as imageTitle.
  • caption: (node) passed to the Lightbox component as imageCaption.

Passing options to Lightbox

The <Gallery> component accepts an object in the lightboxOptions prop, which will be passed down directly to react-image-lightbox.

You can see the full list of options in their documentation.

Passing onClose callback to Lightbox

The <Gallery> component accepts a function in the onClose prop, which will be called when react-image-lightbox is closed by the user.

Customise columns

To customise the number of columns and the space between the images, you have several props:

  • colWidth: percentage of total width to use on small screens (1/3 by default).
  • mdColWidth: percentage of total width to use on medium and large screens (1/4 by default).
  • gutter: margin around each image (0.25rem by default).
  • rowMargin: horizontal margin on each side of the gallery (-15px by default)

Customise image styles

You may also inject your own image styles by passing a component as customWrapper prop. The given component will be passed a few props that you should handle:

  • a GatbsyImage as children, this is the small image
  • a callback as onClick, opening the Lightbox when the small image is clicked

A minimal example may look like this, but you're free to bind the onClick to another element or render the image otherwise:

const CustomWrapper = ({ children, onClick }) => (
  <div className="my-custom-image-wraper" onClick={onClick}>
    {children}
  </div>
)

const MyPage = ({ data }) => {
  return (
    <Gallery
      //... Other props omited for clarity
      customWrapper={CustomWrapper} // example of use
    />
  )
}

Example

For a full working example, there is one in the example folder which is deployed to Netlify.

Development

Releases

Releases are automated using semantic release. This library parses the commit log to detect which version number should be bumped.

License

MIT © browniebroke