Documentation

React Photo Album allows you to build a responsive React photo gallery in minutes. To get started, follow the Installation and Minimal Setup Example guides, or feel free to explore the collection of examples with live demos. The below documentation covers React Photo Album API.

React Photo Album provides all components and types as named exports. PhotoAlbum is exported as both default and named export.

Parameters marked with an asterisk () are required.

PhotoAlbum

Photo

You can pass additional photo attributes and access them inside the renderPhoto function.

<PhotoAlbum
    layout="rows"
    photos={[{ src: "/images/image1.jpg", width: 800, height: 600, href: "https://react-photo-album.com/"}]}
    renderPhoto={({ photo, wrapperStyle, renderDefaultPhoto }) => (
        <a href={photo.href} style={wrapperStyle} target="_blank" rel="noreferrer noopener">
            {renderDefaultPhoto({ wrapped: true })}
        </a>
    )}
/>

ClickHandler

PhotoAlbum accepts a click callback function via the onClick parameter.

ClickHandler Props

ClickHandler Usage Example

<PhotoAlbum
    layout="rows"
    photos={photos}
    onClick={({ index }) => {
        openLightbox(index);
    }}
/>

ResponsiveParameter

PhotoAlbum accepts various props via ResponsiveParameter type.

Responsive parameters can be provided either as a hard-coded number

<PhotoAlbum columns={3} />

or as a function of container width

<PhotoAlbum
    columns={(containerWidth) => {
        if (containerWidth < 400) return 2;
        if (containerWidth < 800) return 3;
        return 4;
    }}
/>

ComponentsPropsParameter

You can pass additional HTML attributes to the rendered elements via the componentsProps parameter. componentsProps prop can be defined either as an object or as a function of an optional container width.

ComponentsProps Usage Example

<PhotoAlbum
    layout="rows"
    photos={photos}
    componentsProps={(containerWidth) => ({
        imageProps: { loading: (containerWidth || 0) > 600 ? "eager" : "lazy" },
    })}
/>

LayoutOptions

LayoutOptions object represents photo album configuration and can be used in custom render functions to access photo album parameters.

RenderPhoto

PhotoAlbum photos can be customized via the renderPhoto render function.

RenderPhoto Props

RenderPhoto Usage Example

<PhotoAlbum
    layout="rows"
    photos={photos}
    renderPhoto={({ photo, wrapperStyle, renderDefaultPhoto }) => (
        <div style={{ position: "relative", ...wrapperStyle }}>
            {renderDefaultPhoto({ wrapped: true })}
            {photo.title && (
                <div
                    style={{
                        position: "absolute",
                        overflow: "hidden",
                        backgroundColor: "rgba(255 255 255 / .6)",
                        inset: "auto 0 0 0",
                        padding: 8,
                    }}
                >
                    {photo.title}
                </div>
            )}
        </div>
    )}
/>

RenderContainer

PhotoAlbum container can be customized via the renderContainer render function.

RenderContainer Props

RenderRowContainer

PhotoAlbum row containers can be customized via the renderRowContainer render function.

RenderRowContainer Props

RenderColumnContainer

PhotoAlbum column containers can be customized via the renderColumnContainer render function.

RenderColumnContainer Props

ResponsiveBreakpoints

By default, PhotoAlbum re-calculates its layout every time its container width changes. For example, the layout may get re-calculated dozens of times during a simple browser window resize. If this behavior is undesired, you can avoid it by providing responsive breakpoints (e.g., [300, 600, 1200] ). When the breakpoints parameter is defined, PhotoAlbum calculates the layout only once per breakpoint interval using the interval's lower boundary as the container width, and the layout is scaled automatically via CSS. On the interval between 0 and the lowest breakpoint, PhotoAlbum uses 1/2 of the lowest breakpoint as the container width. Please also note that it makes sense to use the breakpoints parameter only in conjunction with CSS-based photo props (imageProps.style.width and imageProps.style.width) rather than the exact photo dimensions expressed in pixels (layout.width and layout.height).

<PhotoAlbum
    breakpoints={[300, 600, 1200]}
    // ...
/>

ResponsiveSizes

ResponsiveSizes attribute is only applicable when you use the srcset feature and provide resolution-switching image files via the photos.images attribute. By default, PhotoAlbum assumes 100vw as its on-screen horizontal dimension. To improve sizes attribute accuracy on individual images, you can describe the photo album dimensions under various media conditions via the sizes attribute.

For example, this website uses the following sizes attribute to account for content container padding and the left-hand side navigation menu at various breakpoints:

<PhotoAlbum
    sizes={{
        size: "1600px",
        sizes: [
            { viewport: "(max-width: 429px)", size: "calc(100vw - 32px)" },
            { viewport: "(max-width: 699px)", size: "calc(100vw - 48px)" },
            { viewport: "(max-width: 1887px)", size: "calc(100vw - 240px - 48px)" },
        ],
    }}
    // ...
/>