Pro Gallery

Blazing fast & beautiful galleries built with React. Try it out now.

• Responsive
• Lazy loading
• Infinite Scroll
• Fully Customizable
• Supports images, videos, and HTML

Gettings Started

The best way to get started is by using the Playground. Use the sidebar to configure the gallery layout you need. When you're done, click the Generate Gallery Code button to get the copy-paste-ready code. All you need to do after that is specify the images array for the gallery to process - and your gallery is ready!

Installation

Install with npm

npm i -S pro-gallery

or yarn

yarn add pro-gallery

Basic Code

import { ProGallery } from 'pro-gallery';
import 'pro-gallery/dist/statics/main.css';

<ProGallery
  domId={domId}
  items={items}
  options={options}
  container={container}
  scrollingElement={() => document.getElementById('gallery') || window}
  eventsListener={(eName, eData) => console.log({eName, eData})}
  resizeMediaUrl={(item, url, resizeMethod, width, height) => `https://...`}
  isPrerenderMode={isPrerenderMode}
/>

To see more options and a real usage example, use the playground source code as reference.

Options

The gallery has A LOT of options, so to make it all easier, we created the Playground. Each option is expandable in the sidebar, and has all the info you need about using it. Notice that you can click on Generate Gallery Code anytime to get the code for the gallery layout you created.

Items

For the code you generated to work you need to do just one more thing - provide it with a list of objects, each containing at least an id, dto, and metadata:

const items = [
  { // Image item:
    itemId: 'sample-id',
    mediaUrl: 'sample-image-url',
    metaData: {
      type: 'image',
      height: 200,
      width: 100,
      title: 'sample-title',
      description: 'sample-description',
      focalPoint: [0, 0],
      link: {
        url: 'http://example.com',
        target: '_blank'
      },
    }
  },
  { // Video item:
    itemId: 'sample-id',
    mediaUrl: 'sample-video-url',
    metaData: {
      type: 'video',
      height: 200,
      width: 100,
  		poster: 'sample-image-url',
      title: 'sample-title',
      description: 'sample-description',
      focalPoint: [0, 0],
      link: {
        url: 'http://example.com',
        target: '_blank'
      },
    }
  },
  { // HTML item:
    itemId: 'sample-id',
    html: "<div style='width: 300px; height: 200px; background:pink;'>I am a text block</div>",
    metadata: {
      type: "text",
      height: 200,
      width: 300,
      title: 'sample-title',
      description: 'sample-description',
      backgroundColor: 'pink'
    },

  },
  {...},
  {...}
]

Container

An object containing the width and height (in pixels) of the gallery. These values should change when the container resizes, to allow the gallery to be responsive.

const container = {
  width: 1000,
  height: 500,
}

The width and height values represent the size of the gallery. Thus, the gallery will size inner items to fit exactly into that size. Notice that when infiniteScroll is enabled, vertical galleries will ignore the height parameter and horizontal galleries will ignore the width parameter.

domId

A unique Id for the gallery. Use this if you plan to display multiple galleries on the same page, or when using SSR - to make sure the gallery does not "flicker" in the hydrate phase.

Scrolling Element

The DOM element inside which the gallery is scrolled (defaults to window). If the gallery is scrolled inside a different element, pass its dom reference in this property. You can also pass a function that returns that dom element. notice: this is relevant to vertical galleries only. Horizontal galleries (e.g. slideshow) are handling the scroll themselves.

Events Listener

A callback function that gets called whenever something happens in the gallery. This allows you to react to specific events. The most important events are:

The full list of the gallery events is here.

Media URL Resizer

If you want to use a server-side resizing service (e.g. cloudinary), you can pass a resizing function. This function receives the item and required dimensions and should return the resize url. Notice that this function will be called several times for each item so it should be fast. An example can be found here

Prerender Mode

The prerender mode is a special middle phase for situations where the gallery is rendered in a responsive layout in SSR - without the real container measurements. This render will not be accurate until the client will "fix" the layout (since the server cannot measure the size of the container). When passing the gallery a "fake" container measurements, you'll need to pass this parameter as true to let the gallery know it should only prepare the html, but wait for the real measurements before showing the gallery

Custom Renderers

The Gallery supports custom renderers both for the Hover Element (appears when hovering over an item) and the Info Element (appears below / above an item). To replace the default rendering of these elements, pass a function that will receive the props of an item and that in turn should return a JSX element. For example:

<ProGallery
  {...otherProps}
  customHoverRenderer={itemProps => <div>Hover #{itemProps.idx}</div>}
  customInfoRenderer={itemProps => <div>Info #{itemProps.idx}</div>}
  customImageRenderer={imageProps => <img {...imageProps} />}
  customLoadMoreRenderer={galleryProps => <button>Load More</button>}
  customNavArrowsRenderer={direction => <button>{direction}</button>}
/>

Version 3

Version 3 introduces a clear separation between logic and rendering in the pro-gallery.

The ProGalleryRenderer is a new export of the pro-gallery. It will expect a ready gallery Blueprint spread into the props it receives.

Blueprint

We call the result of all the calculations that the ProGalleryRenderer needs a Blueprint.

To create a Blueprint we need :

• Styles
• Items
• Container
• totalItemsCount

The result is an object containing the processed styles, items,container and structure to be passed to the ProGalleryRenderer as props.

Benefits of splitting

With the code that calculates the blueprint split from the rendering components we can create the blueprint for the gallery wherever we want and only import the rendering code (smaller) in the main thread. The blueprint itself can be calculated in a web worker or even in a server.

To learn how to use the Blueprints and the BlueprintsManager go to the pro-gallery-lib readme.