React Headless Gallery

Headless, zero-dependencies, gallery/carousel component.

Features

• Infinite sliding (circular gallery)
• Sliding animation (configurable)
• Self looping (configurable)
• Gallery indicators
• Allows for lazy loading of gallery items (see example below)
• Freely style and position all elements of the component
• Built with accessibility in mind (see accessibility below)

Install

npm install react-headless-gallery

yarn add react-headless-gallery

Example

Click here for a live demo

Code Example

The following code example uses TailwindCSS to style the gallery, as shown in the image above:

function MyGallery() {
  const items = [
    {
      id: 1,
      content: (
        <img alt="Item 1" src="..." />
      ),
    },
    {
      id: 2,
      content: (
        <img alt="Item 2" loading="lazy" src="..." />
      ),
    },
    {
      id: 3,
      content: (
        <img alt="Item 3" loading="lazy" src="..." />
      ),
    },
  ] as const;

  return (
    <div className="w-full h-full bg-white p-32">
      <Gallery className="flex flex-col items-center gap-4">
        <div className="flex flex-row gap-2 items-center">
          <Gallery.Prev className="cursor-pointer text-gray-800">
            <LeftSVG />
          </Gallery.Prev>
          <Gallery.Items className="w-[640px]">
            {items.map((item) => (
              <Gallery.Item key={item.id}>
                {item.content}
              </Gallery.Item>
            ))}
          </Gallery.Items>
          <Gallery.Next className="cursor-pointer text-gray-800">
            <RightSVG />
          </Gallery.Next>
        </div>
        <div className="flex flex-row gap-2">
          {[...Array(items.length)].map((_, i) => (
            <Gallery.Indicator
              key={i}
              galleryItemIndex={i}
              className={(isCurrent) =>
                `text-sm cursor-pointer ${isCurrent ? "text-gray-800" : "text-gray-300"}`
              }
            >
              ⬤
            </Gallery.Indicator>
          ))}
        </div>
      </Gallery>
    </div>
  );
}

Accessibility

The gallery's controls (next, prev, and indicators) are buttons with ARIA labels that can be changed. They are defined as controlling the gallery container with the aria-controls attribute. Please note that all items in the gallery will have the aria-hidden attribute, except for the item that is currently being shown. Items in the gallery should not include focusable elements.

API

Gallery

Name	Type	Description
transitionDurationMS	number	The duration of the transition in milliseconds. Default: 300.
transitionTimingFunction	EasingFunction	The timing function for the transition. Default: ease-in-out.
selfLooping	false | number	Enable self-looping. If a number is provided, it will be used as the looping interval in milliseconds. Default: false
stopLoopingOnInteraction	boolean	If true, self looping will stop when the gallery is interacted with (default: true)
className	string	Additional CSS classes to apply to the component.
style	React.CSSProperties	Inline styles to apply to the component.
ref	React.Ref<HTMLDivElement>	ref object to the HTML container element.

Gallery.Indicator

Name	Type	Description
galleryItemIndex	number	The index of the item to switch to.
aria-label	string | ((itemNumber: number, isCurrent: boolean) => string)	ARIA label for the button.
className	string | ((isCurrent: boolean) => string)	Additional CSS classes to apply to the component.
style	React.CSSProperties	Inline styles to apply to the button.
ref	React.Ref<HTMLButtonElement>	ref object to the HTML button element.

Gallery.Prev and Gallery.Next

Name	Type	Description
aria-label	string	ARIA label for the button.
className	string	Additional CSS classes to apply to the component.
style	React.CSSProperties	Inline styles to apply to the button.
ref	React.Ref<HTMLButtonElement>	ref object to the HTML button element.

Note on infinite sliding

To implement infinite sliding, the first and last gallery elements are cloned - each will appear twice in the DOM. If that causes undesirable side effects, please create an issue.