react-photoswipe-gallery

A configurable and flexible React component wrapper around PhotoSwipe.

ℹ️ Current version of react-photoswipe-gallery is compatible with PhotoSwipe v5.
If you need PhotoSwipe v4, use react-photoswipe-gallery v1.

Basic Usage

1import 'photoswipe/dist/photoswipe.css'
2
3import { Gallery, Item } from 'react-photoswipe-gallery'
4
5const MyGallery = () => (
6  <Gallery>
7    <Item
8      original="https://placekitten.com/1024/768?image=1"
9      thumbnail="https://placekitten.com/80/60?image=1"
10      width="1024"
11      height="768"
12    >
13      {({ ref, open }) => (
14        <img ref={ref} onClick={open} src="https://placekitten.com/80/60?image=1" />
15      )}
16    </Item>
17    <Item
18      original="https://placekitten.com/1024/768?image=2"
19      thumbnail="https://placekitten.com/80/60?image=2"
20      width="1024"
21      height="768"
22    >
23      {({ ref, open }) => (
24        <img ref={ref} onClick={open} src="https://placekitten.com/80/60?image=2" />
25      )}
26    </Item>
27  </Gallery>
28)

Demo

Check out the Storybook to see it in action 🚀

Stories are written as real-world examples, so you can see them at the bottom of Storybook UI in the Story tab. Or browse the source code on GitHub. It covers most of the use-cases and provides examples for configuration options.

Installation

1yarn add photoswipe react-photoswipe-gallery

or

1npm install photoswipe react-photoswipe-gallery --save

Hash Navigation

You should pass a unique id prop to <Gallery /> component, to enable hash navigation.

Optionally, you can also pass the id to <Item /> component. Otherwise, the index will be used.

1const MyGallery = () => (
2  <Gallery id="my-gallery">
3    <Item
4      id="first-pic"
5      {/*...*/}
6    />
7    <Item
8      id="second-pic"
9      {/*...*/}
10    />
11  </Gallery>
12)

Example

Captions

If you want to add captions to your slides, you need to pass withCaption prop to the <Gallery /> and pass caption prop to each <Item />. It accepts html as well. If caption isn't provided - it will use alt prop.

1const MyGallery = () => (
2  <Gallery withCaption>
3    <Item
4      caption="Foo"
5      {/*...*/}
6    />
7    <Item
8      alt="Bar"
9      {/*...*/}
10    />
11  </Gallery>
12)

Example

Plugins

You can use native PhotoSwipe plugins with plugins prop. It accepts the function in which you should register all of your plugins, providing pswpLightbox to the plugin constructor.

Example for photoswipe-dynamic-caption-plugin:

1import 'photoswipe-dynamic-caption-plugin/photoswipe-dynamic-caption-plugin.css'
2import PhotoSwipeDynamicCaption from 'photoswipe-dynamic-caption-plugin'
3
4const MyGallery = () => (
5  <Gallery
6      plugins={(pswpLightbox) => {
7        // register plugin
8        const captionPlugin = new PhotoSwipeDynamicCaption(pswpLightbox, {
9          captionContent: (slide) => slide.data.alt,
10        })
11
12        // register another plugin
13        // ...
14      }}
15  >
16    {/*...*/}
17  </Gallery>
18)

Example

Custom UI Elements

You can add custom UI elements to PhotoSwipe with uiElements prop. It accepts an array of configuration objects for custom UI elements.

1const uiElements = [
2  // add custom UI element
3  {
4    name: 'custom-button',
5    ariaLabel: 'Custom button',
6    order: 9,
7    isButton: true,
8    html: {
9      isCustomSVG: true,
10      inner:
11        '<path d="<ICON_PATH>" id="pswp__icn-cstm-btn"/>',
12      outlineID: 'pswp__icn-cstm-btn',
13    },
14    appendTo: 'bar',
15    onInit: (el, pswpInstance) => {
16      // do something on UI element's init event
17    },
18    onClick: (e, el, pswpInstance) => {
19      // do something on UI element's click event
20    },
21  },
22
23  // add another custom UI element
24  // ...
25]
26
27const MyGallery = () => (
28  <Gallery uiElements={uiElements}>
29    {/*...*/}
30  </Gallery>
31)

Example

Custom slide content

You can add your own custom slide content with content and html props.

1const MyGallery = () => (
2  <Gallery>
3    <Item
4      content={<h1>Hi!</h1>}
5      {/*...*/}
6    />
7    <Item
8      html="<h1>Hi!</h1>"
9      {/*...*/}
10    />
11  </Gallery>
12)

Example

Data source

You can pass slides data to Photoswipe not only via Item component. You can also do it via dataSource prop.

1const dataSource = [
2  {
3    sourceId: 1, // needed to connect following data with Item component
4    original: "https://placekitten.com/1024/768?image=1",
5    thumbnail: "https://placekitten.com/80/60?image=1",
6    width: "1024",
7    height: "768",
8  },
9  {
10    sourceId: 2,
11    ...
12  },
13  {
14    sourceId: 3,
15    ...
16  },
17]
18
19const MyGallery = () => (
20  <Gallery dataSource={dataSource}>
21    <Item
22      sourceId={1} // needed to connect Item component with data from dataSource
23    >
24      {({ ref, open }) => (
25        <button type="button" ref={ref} onClick={open}>
26          Open gallery at first slide
27        </button>
28      )}
29    </Item>
30  </Gallery>
31)

Example

Also dataSource prop can be helpful, if you need to render only some part of images as thumbnails and show all available images in Photoswipe.

1const dataSource = [
2  {
3    sourceId: 1, // needed to connect following data with Item component
4    original: "https://placekitten.com/1024/768?image=1",
5    thumbnail: "https://placekitten.com/80/60?image=1",
6    width: "1024",
7    height: "768",
8  },
9  {
10    sourceId: 2,
11    ...
12  },
13  {
14    sourceId: 3,
15    ...
16  },
17  {
18    sourceId: 4,
19    ...
20  },
21  {
22    sourceId: 5,
23    ...
24  },
25]
26
27const MyGallery = () => (
28  <Gallery dataSource={dataSource}>
29    <Item
30      sourceId={1} // needed to connect Item component with data from dataSource
31    >
32      {({ ref, open }) => (
33        <img
34          src="https://placekitten.com/80/60?image=1"
35          ref={ref}
36          onClick={open}
37        />
38      )}
39    </Item>
40    <Item
41      sourceId={2}
42    >
43      {({ ref, open }) => (
44        <img
45          style={imageStyles}
46          src="https://placekitten.com/80/60?image=2"
47          ref={ref}
48          onClick={open}
49        />
50      )}
51    </Item>
52    <Item
53      sourceId={3}
54    >
55      {({ ref, open }) => (
56        <div ref={ref} onClick={open}>
57          <p>+ 2</p>
58          <img
59            src="https://placekitten.com/80/60?image=3"
60          />
61        </div>
62      )}
63    </Item>
64  </Gallery>
65)

Example

Access to Photoswipe instance

If you need to get access to Photoswipe instance (for example, to subscribe on Photoswipe events or call some Photoswipe method), you can do it via onOpen and onBeforeOpen props of Gallery component.

onBeforeOpen triggers before PhotoSwipe.init() call.

onOpen triggers after PhotoSwipe.init() call.

onBeforeOpen and onOpen will receive PhotoSwipe instance as the first argument.

1const onBeforeOpen = (pswpInstance) => {
2  pswpInstance.on('change', () => {
3    console.log('slide was changed')
4  })
5}
6
7const onOpen = (pswpInstance) => {
8  pswpInstance.currSlide.zoomTo(
9    1,
10    { x: 0, y: 0 },
11    2000,
12    false
13  )
14}
15
16const MyGallery = () => (
17  <Gallery onBeforeOpen={onBeforeOpen} onOpen={onOpen}>
18    {/*...*/}
19  </Gallery>
20)

Photoswipe customization

If you need to customize Photoswipe options or Photoswipe styling you can do it via options prop of Gallery component.

1const options = {
2  arrowPrev: false,
3  arrowNext: false,
4  zoom: false,
5  close: false,
6  counter: false,
7  bgOpacity: 0.2,
8  padding: { top: 20, bottom: 40, left: 100, right: 100 },
9}
10
11const MyGallery = () => (
12  <Gallery options={options}>
13    {/*...*/}
14  </Gallery>
15)

Props

Gallery

Prop	Type	Required	Description
id	Number or String	✓ (for hash navigation)	Item ID, for hash navigation
options	Object		Object containing PhotoSwipe options and styling properties
plugins	Function		Function for registering PhotoSwipe plugins. You should pass photoswipeLightbox to each plugin constructor (example)
uiElements	Array		Array of configuration objects for custom UI elements. Use it for adding custom UI elements (example)
onBeforeOpen	Function		Triggers before PhotoSwipe.init() call. Use it for accessing PhotoSwipe API. It will receive PhotoSwipe instance as the first argument: (photoswipe: PhotoSwipe) => void
onOpen	Function		Triggers after PhotoSwipe.init() call. Use it for accessing PhotoSwipe API. It will receive PhotoSwipe instance as the first argument: (photoswipe: PhotoSwipe) => void
withCaption	Boolean	✓ (for default captions)	Enables built-in caption display. Use the caption prop of the Item component to control caption text (example)
withDownloadButton	Boolean	✓ (for download button)	Adds UI control for downloading the original image of the current slide (example)
dataSource	Array		Array of data for Photoswipe slides. Data source - alternative way to pass data into Photoswipe

Item

Should be children of the Gallery.

Prop	Type	Required	Description
children	Function	✓	Render prop for exposing Gallery API
original	String		Url of original image
originalSrcset	String		Srcset of original image (example)
thumbnail	String		Url of thumbnail
width	Number or String		Width of original image
height	Number or String		Height of original image
alt	String		Alternate text for original image
caption	String		Text or html for caption (example)
cropped	Boolean		Thumbnail is cropped (example)
content	ReactElement		Custom slide content (example)
html	String		Custom slide content (raw html) (example)
id	Number or String		Item ID, for hash navigation (example)
sourceId	Number or String	✓ (for data source)	Item source ID, that will be used to identify item in dataSource array (example)

Note about Item's children render prop

Item accepts only function as children.

1export interface ChildrenFnProps<NodeType extends HTMLElement> {
2  /**
3   * Ref callback to any html node of item.
4   * It must be set to HTML Element in order to work.
5   * Can be done like usual ref: ref={ref}
6   * or callback-way if you need extra work done with node:
7   * ref={(node) => {
8   *   ref(node)
9   *   ...
10   * }}
11   */
12  ref: (node: NodeType | null) => void
13
14  /**
15   * Function that opens the gallery at the current item
16   */
17  open: (e: MouseEvent) => void
18
19  /**
20   * Function that closes the gallery
21   */
22  close: () => void
23}
24
25<Item>
26  {({ ref, open }) => (
27    <img ref={ref} onClick={open} />
28  )}
29</Item>
30
31<Item>
32  {({ ref, open, close }) => (
33    <>
34      <span
35        ref={(node) => {
36          ref(node)
37        }}
38        onClick={open}
39      >
40        Open gallery
41      </span>
42      <span
43        ref={(node) => {
44          ref(node)
45        }}
46        onClick={close}
47      >
48        Close gallery
49      </span>
50    </>
51  )}
52</Item>

Hooks

useGallery

The useGallery hook returns an object with some useful methods.

Property	Type	Description
open	(index: number) => void	This function allows programmatically open Photoswipe UI at index
close	() => void	This function allows programmatically close Photoswipe UI

useGallery hook gets context provided by Gallery component. So to use useGallery hook you need to store your gallery content as separate component and then wrap it into Gallery component.

1const GalleryContent = () => {
2  const { open, close } = useGallery()
3
4  useEffect(() => {
5      open(1) // you can open second slide by calling open(1) in useEffect
6
7      setTimeout(() => {
8        close() // or you can close gallery
9      }, 5_000)
10  }, [open, close])
11
12  return (
13    <div>
14      {/* you can open second slide on button click */}
15      <button onClick={() => open(1)}>Open second slide</button>
16      {/* or close gallery */}
17      <button onClick={close}>Close gallery</button>
18      <div>
19        <Item>...</Item>
20        <Item>...</Item>
21        <Item>...</Item>
22      </div>
23    </div>
24  )
25}
26
27const MyGallery = () => {
28  return (
29    {/* Gallery component provides context for useGallery hook used in GalleryContent */}
30    <Gallery>
31      <GalleryContent />
32    </Gallery>
33  )
34}

Example 1, Example 2

Requirements

• react@16.8+
• Map polyfill for older browsers

Development

1yarn install
2yarn sdks vscode

then

1yarn storybook

or

1yarn start

License

MIT