Need help with pro-gallery?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

139 Stars 19 Forks MIT License 3.2K Commits 59 Opened issues


Blazing fast & beautiful galleries built for the web

Services available


Need anything else?

Contributors list

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

NPM Version Build Status

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
for the gallery to process - and your gallery is ready!


Install with

npm i -S pro-gallery
yarn add pro-gallery

Basic Code

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

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.


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.


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: ```jsx 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: '', 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: '', target: 'blank' }, } }, { // HTML item: itemId: 'sample-id', html: "

I am a text block
", metadata: { type: "text", height: 200, width: 300, title: 'sample-title', description: 'sample-description', backgroundColor: 'pink' },

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


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,
values represent the size of the gallery. Thus, the gallery will size inner items to fit exactly into that size. Notice that when
is enabled, vertical galleries will ignore the
parameter and horizontal galleries will ignore the


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

). 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:

| Event Name | Description | | --------------- | ----------- | |

| Fired whenever the gallery finished rendering, usually after the props were changed. This event contains the structure data of the gallery. | |
| Fired whenever one of the items is clicked or tapped and the gallery cannot handle the action itself (e.g. open an expanded view). | |
| Fired whenever the gallery is scrolled near its last item. If you are using a pagination server, this is the event that should trigger the next page and re-render the gallery with new items. |

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

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:

Hover #{itemProps.idx}
} customInfoRenderer={itemProps =>
Info #{itemProps.idx}
} customImageRenderer={imageProps => } customLoadMoreRenderer={galleryProps => Load More} customNavArrowsRenderer={direction => {direction}} />

Version 3

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


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


We call the result of all the calculations that the

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.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.