@wethegit/react-gallery v4.0.1

@wethegit/react-gallery

A slideshow-style gallery component for use in React projects.

• Getting started
  • Starter example
• Custom layouts
• Components and options
  • Gallery
  • GalleryMain
  • GalleryItem
  • GalleryNav
  • GalleryPagination
  • GalleryPaginationItem
• Accessibility
• useGallery hook
  • Advanced customization
  • Usage

Features

• Accessibility. Built with careful attention to focus management and assistive technology.
• Fully-customizable layouts, using CSS Custom Properties.
• Provides a custom React hook for accessing gallery data, state, updater functions, and more. Build anything on top of the existing gallery components!

Getting started

Install the package

npm install @wethegit/react-gallery
-or-
yarn add @wethegit/react-gallery

Import the Components and—optionally—the hook.

import {
  Gallery,
  GalleryMain,
  GalleryItem,
  GalleryNav,
  GalleryPagination,
  GalleryPaginationItem,
  useGallery,
} from "@wethegit/react-gallery"

Import the base stylesheet

This is an optional step, but it's highly recommended to use the base styles as a starting point. The most straightforward way to do this is to import the stylesheet into your app directly from the /node_modules/@wethegit/react-gallery/dist/ directory, but you can do this in whichever way is preferable within your build system or framework.

// app.js

import "@wethegit/react-gallery/style.css"

Create a simple Gallery

The <Gallery> component is a React context provider, which gives all child components access to relevant data. All child components that need access to gallery data must live within a <Gallery>. Here's an example of a gallery, given the following contrived data GALLERY_ITEMS. This will be explained in detail shortly.

⚠️ Before continuing, make sure you have properly imported the base stylesheet, if you intend to use it.

// some-data.js

export const GALLERY_ITEMS = [
  { image: "/my-image-1.png", alt: "Description of image!", id: 131789 },
  { image: "/my-image-2.png", alt: "Description of image!", id: 235233 },
  { image: "/my-image-3.png", alt: "Description of image!", id: 987432 },
  { image: "/my-image-4.png", alt: "Description of image!", id: 768324 },
]

// your-gallery.js

import { GALLERY_ITEMS } from "./some-data"
import {
  Gallery,
  GalleryMain,
  GalleryNav,
  GalleryPagination,
  GalleryPaginationItem,
  GalleryItem,
} from "@wethegit/react-gallery"

const YourGallery = () => {
  return (
    <Gallery items={GALLERY_ITEMS}>

      <GalleryMain
        renderGalleryItem={({ item, index, active }) => (
          <GalleryItem key={item.id} index={i} active={active}>
            <img src={item.image} alt={item.alt} />
          </GalleryItem>
        )}
      />

      <GalleryNav direction={0}>⬅️</GalleryNav>
      <GalleryNav direction={1}>➡️</GalleryNav>

      <GalleryPagination
        renderPaginationItem={({ item, index, active }) => (
          <GalleryPaginationItem key={item.id} index={index} active={active}>
            <span>{i + 1}</span>
          </GalleryPaginationItem>
        )}
      />

    </Gallery>
  )
}

export default YourGallery

The first step is to give your data to the <Gallery> component via the items prop. At the very least, items is expected to be an Array. From there, you're free to arrange the child components this package provides as you see fit. Below is a brief description of each of the child components' usage. For a detailed breakdown of this component, jump ahead to the Gallery section.

<GalleryMain> is the primary gallery view where your item data is rendered. It receives a render prop, renderGalleryItem, which exposes a few arguments you can use in the JSX you return: item, index, activeIndex, and active and expects a <GalleryItem> to be returned. For a detailed breakdown of this component, jump ahead to the GalleryMain section.

We're using the <GalleryNav> component to define our "next" and "previous" buttons. These components receive a direction prop, which expects either a 1 or a 0, and corresponds to the direction the gallery should move in when the button in question is clicked (where 0 maps to "previous", and 1 maps to "next"). For a detailed breakdown of this component, see the GalleryNav section.

We're also using the <GalleryPagination> and GalleryPaginationItem components here. If you're not familiar, "pagination" refers to what is often rendered as a set of "dots" below a gallery — but this can be anything (thumbnails, icons, and so on). This component receives the render prop, renderPaginationItem, which exposes a few arguments you can use in the JSX you return: item, i, activeIndex, and active. The easiest way to link up you pagination is to use the <GalleryPaginationItem> component, as shown in the example above. For a detailed breakdown of this component, jump ahead to the GalleryPagination section.

Custom layouts

Assuming the base stylesheet is being used, the <GalleryMain> component renders as a CSS grid, with a single grid area to house the currently-active item. There are a number of CSS custom properties on the various gallery components, which will allow you to customize the look of the gallery. Most of these properties are used to calculate the horizontal positioning of the gallery items around the main grid cell, and can be adjusted to create many different layout variations. Remove the transform property of a .gallery__item entirely, and you'll get a traditional, stacked gallery.

Components and options

<Gallery>

The parent component for all gallery instances. This serves as a React context provider to its children.

Props:

ariaLiveText

Per the WAI-ARIA spec, browsers using assistive technology such as screen readers announce content within a DOM element containing the aria-live attribute, anytime it changes. The gallery component's default value for this prop is "Item $i of $t.". The variables $i and $t here correspond to "current index" and "total number of items", and will be replaced with those values when rendered. This level of customization is provided so that you can localize/translate your content with accuracy.

onChange

The onChange callback allows you to run code whenever the active gallery item changes. It receives a single Object as an argument, containing the following properties:

<GalleryMain>

The primary gallery body. Must be used within a <Gallery>. Renders an unordered list (<ul>) of your gallery items.

Props:

renderGalleryItem

This render prop expects a <GalleryItem> to be returned, and receives a handful of arguments:

<GalleryItem>

Required component that wraps each child inside the renderGalleryitem prop. Renders a list item (<li>) and can accept the following props:

<GalleryNav>

The navigational "next" and "previous" buttons. Must be used within a <Gallery>. You can render your buttons either by passing regular JSX children to them, or by using the renderNavItem render prop.

Props:

renderNavItem

This render prop is a nice alternative to simply passing childern to the <GalleryNav>, as it provides you with a handful of arguments, as outlined below:

<GalleryPagination>

Renders an unordered list (<ul>) of pagination items. Must be used within a <Gallery>.

Props:

renderPaginationItem

This render prop receives a handful of arguments, and is necessary for rendering pagination UI:

Example usage of renderPaginationItem render prop

<GalleryPagination
  renderPaginationItem={({ index, active, activeIndex, item }) => (
    <GalleryPaginationItem index={index} active={active} key={item.id}>
      <span>{index + 1}</span>
    </GalleryPaginationItem>
  )}
/>

<GalleryPaginationItem>

Used in the prop renderPaginationItem of <GalleryPagination>. This component with a return value in a list item (<li>) and a <button>, and receives a handful of arguments:

Props:

Example usage of GalleryPaginationItem

const handlePaginationItemClick = ({ event, index }) => {
  console.log(event, index)
}

<GalleryPagination
  renderPaginationItem={({ index, active, item }) => (
    <GalleryPaginationItem
      index={index}
      active={active}
      key={item.id}
      onClick={handlePaginationItemClick}
    >
      <span>{index + 1}</span>
    </GalleryPaginationItem>
  )}
/>

Accessibility

The gallery component handles tabbing, focus management, and live-region announcements out-of-the-box. All relevant patterns used in this component follow the guidelines for carousels as documented by the Web Accessibility Initiative.

That said, you must still code responsibly! Ensure that your gallery contents, nav buttons, and pagination items all have discernible text — whether that be image alt text, or visually-hidden text intended for screen readers (the stylesheet included with the Gallery component inclues a CSS utility class for this: .gallery-util-visually-hidden).

Regarding the ARIA-live text, check out the section on this gallery's ariaLiveText prop.

Reduced motion

For reduced motion implementations, you can detect the user's preference via the matchMedia API, and adjust the CSS custom property, --duration on the .gallery selector. Check out the example below, which adds a style tag to the gallery, and overrides the --duration property based on the preference. You could also do this via a conditional className, if you prefer. An alternative is be to pass this prefersReducedMotion value as a prop, which could be helpful if you use the Styled Components library.

const YourGallery = () => {
  // Get the user's motion preference:
  const prefersReducedMotion = window.matchMedia(
    "(prefers-reduced-motion: reduce)"
  ).matches

  // Create an inline style object
  const style = {
    "--duration": prefersReducedMotion ? "0s" : "0.5s",
  }

  return (
    // Pass the style overrides to the <Gallery> component
    <Gallery items={GALLERY_ITEMS} style={style}>
      <GalleryMain
        renderGalleryItem={({ item, index, active }) => (
          <GalleryItem key={item.id} index={index} active={active}>
            <img src={item.image} alt={item.alt} />
          </GalleryItem>
        )}
      />
      {/* ...etc */}
    </Gallery>
  )
}

useGallery hook

The gallery package exposes a useGallery React hook. It returns a single object, the properties of which are outlined below.
⚠️ useGallery must be called from within a <Gallery> context.

Advanced customization

As you can see above, many of the properties returned by the useGallery hook provide the lower-level functionality for the gallery itself. You can use this data to create any custom implementation you like, without having to worry too much about what's happening behind the scenes.

Usage

Here's an example of a custom component that uses the useGallery hook to simply render a paragraph with some information about the gallery's current state:

import { useGallery } from "@wethegit/react-gallery"

const GalleryInfo = () => {
  const { activeIndex, previouslyActiveIndex, loop } = useGallery()

  return (
    <p>
      The gallery's current index is {activeIndex}, its last index was {previouslyActiveIndex},
      and its <code>loop</code> prop is set to {String(loop)}!
    </p>
  )
}

export default GalleryInfo