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

PropertyTypeDescription
photosPhoto[]
An array of photos to display in the photo album. See Photo for details.
layout'columns' | 'rows' | 'masonry'Photo album layout type.
columnsResponsiveParameter

A number of columns in the columns or masonry layout. See ResponsiveParameter for details.

Default responsive value:

  • 5, when container width >= 1200
  • 4, when container width >= 600 and < 1200
  • 3, when container width >= 300 and < 600
  • 2, when container width < 300
spacingResponsiveParameter

Spacing between images (similar to CSS grid gap). See ResponsiveParameter for details.

Default responsive value:

  • 20, when container width >= 1200
  • 15, when container width >= 600 and < 1200
  • 10, when container width >= 300 and < 600
  • 5, when container width < 300
paddingResponsiveParameter

Padding around each image in the photo album. See ResponsiveParameter for details.

Default value: 0

targetRowHeightResponsiveParameter

Target row height in the rows layout. See ResponsiveParameter for details.

Default responsive value:

  • (container width) / 5, when container width >= 1200
  • (container width) / 4, when container width >= 600 and < 1200
  • (container width) / 5, when container width >= 300 and < 600
  • (container width) / 2, when container width < 300
rowConstraintsResponsiveParameter​<RowConstraints>

Additional row constraints in the rows layout.

  • minPhotos - minimum number of photos per row
  • maxPhotos - maximum number of photos per row
sizesResponsiveSizes

Photo album container width at various viewport sizes. See ResponsiveSizes for details.

Default value: 100vw

onClickClickHandler
Photo click callback function. See ClickHandler for details.
breakpointsnumber[]
Responsive breakpoints. See ResponsiveBreakpoints for details.
defaultContainerWidthnumber

Default container width in SSR.

componentsPropsComponentsPropsParameter

Additional HTML attributes to be passed to the rendered elements. See ComponentsPropsParameter for details.

renderPhotoRenderPhoto
Custom photo rendering function. See RenderPhoto for details.
renderContainerRenderContainer
Custom container rendering function. See RenderContainer for details.
renderRowContainerRenderRowContainer
Custom row container rendering function. See RenderRowContainer for details.
renderColumnContainerRenderColumnContainer

Custom column container rendering function. See RenderColumnContainer for details.

Photo

PropertyTypeDescription
keystring
Optional key attribute.
srcstringImage source.
widthnumberImage width in pixels.
heightnumberImage height in pixels.
altstring
Optional image alt attribute.
titlestring
Optional image title attribute.
images

{
  src: string;
  width: number;
  height: number;
}[]

Optional array of alternative images to be included in the srcset attribute.

All images in a given Photo object must be of the same aspect ratio.

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

PropertyTypeDescription
indexnumberPhoto index.
photoPhotoOriginal photo object.
eventReact.MouseEventCorresponding mouse event.

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.

PropertyTypeDescription
containerPropsHTMLAttributes​<HTMLDivElement>
Additional HTML attributes to be passed to the outer container div element.
rowContainerPropsHTMLAttributes​<HTMLDivElement>
Additional HTML attributes to be passed to the row container div element.
columnContainerPropsHTMLAttributes​<HTMLDivElement>
Additional HTML attributes to be passed to the column container div element.
imagePropsImgHTMLAttributes​<HTMLImageElement>

Additional HTML attributes to be passed to the photo img element.

Default: { loading: "lazy", decoding: "async" }

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.

PropertyTypeDescription
layout'columns' | 'rows' | 'masonry'Photo album layout type.
spacingnumberLayout spacing (gaps between photos).
paddingnumberPadding around each photo.
containerWidthnumber
Current photo album container width. Defaults to defaultContainerWidth when rendered server-side.
onClickClickHandler | undefined
Photo click handler. See ClickHandler for details.
sizesResponsiveSizes | undefined
PhotoAlbum size at various viewport sizes. See ResponsiveSizes for details.
columnsnumber | undefined
Number of columns in columns or masonry layout.
targetRowHeightnumber | undefined
Target row height in rows layout.
rowConstraintsRowConstraints | undefined
Additional row constraints. See RowConstraints for details.

RenderPhoto

PhotoAlbum photos can be customized via the renderPhoto render function.

RenderPhoto Props

PropertyTypeDescription
photoPhoto
Photo object. See Photo for details.
layoutPhotoLayout

Computed photo layout. Please note that width and height are expressed in content-box notation.

  • width - photo width
  • height - photo height
  • index - photo index in the original photos array
  • photoIndex - photo index in a given row or column
  • photosCount - total number of photos in a given row or column
layoutOptionsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
imagePropsImgHTMLAttributes​<HTMLImageElement>

Pre-populated img element attributes (display, box-sizing, width, height, aspect-ratio, padding, margin-bottom and cursor).

renderDefaultPhoto(options?: { wrapped?: boolean }) => ReactNode

A callback to render the default photo implementation. If wrapped is true, the image is styled with width and height set to 100%. Use this option when rendering image wrapper styled with wrapperStyle.

wrapperStyleCSSProperties
CSS styles to properly size image wrapper (i.e. <div/> or <a/> wrapper)

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

PropertyTypeDescription
layout'columns' | 'rows' | 'masonry'Photo album layout type.
containerPropsHTMLAttributes​<HTMLDivElement>

Pre-populated default container attributes (display, flex-wrap, flex-direction and justify-content).

containerRefRefCallback​<HTMLDivElement>
Custom <div/> container ref callback.

RenderRowContainer

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

RenderRowContainer Props

PropertyTypeDescription
layoutOptionsRowsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
rowIndexnumberRow number.
rowsCountnumberTotal number of rows.
rowContainerPropsHTMLAttributes​<HTMLDivElement>

Pre-populated default row container attributes (display, flex-wrap, flex-direction, justify-content, align-items and margin-bottom).

RenderColumnContainer

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

RenderColumnContainer Props

PropertyTypeDescription
layoutOptionsColumnsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
columnIndexnumberColumn index.
columnsCountnumberTotal number of columns.
columnsGapsnumber[] | undefined

Sum of spacings and paddings in each column. columnsGaps property is not provided in the masonry layout.

columnsRatiosnumber[] | undefined
Width adjustment ratios of each column. columnsRatios property is not provided in the masonry layout.
columnContainerPropsHTMLAttributes​<HTMLDivElement>

Pre-populated default column container attributes (display, flex-wrap, flex-direction, justify-content, align-items and width).

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)" },
        ],
    }}
    // ...
/>