Documentation

React Photo Album allows you to build a responsive photo gallery in React in minutes. To get started, follow the Installation and Minimal Setup Example guides, or feel free to explore the collection of CodeSandbox 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
photos
An array of photos to display in the photo album.
layout'columns' | 'rows' | 'masonry'Photo album layout type.
columns

A number of columns in the columns or masonry layout.

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
spacing

Spacing between images (similar to CSS grid gap).

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
padding

Padding around each image in the photo album.

Default value: 0

targetRowHeight

Target row height in the rows layout.

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
rowConstraints
Additional row constraints.
columnConstraints
Additional column constraints.
sizes

Photo album width at various viewport sizes.

Default value: 100vw

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

Default container width to be used in the server-side render. defaultContainerWidth value affects all responsive parameters that depend on containerWidth.

Default value: 800

componentsPropsAdditional HTML attributes to be passed to the rendered elements.
renderPhotoCustom photo rendering function.
renderContainerCustom container rendering function.
renderRowContainerCustom row container rendering function
renderColumnContainerCustom column container rendering function
resizeObserverProvider
ResizeObserver factory to be used when global ResizeObserver is unavailable.

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
Array<{src, width, height}>
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.

Additional attributes can be added to the Photo object by extending the Photo interface.

interface CustomPhoto extends Photo {
    customAttribute?: string;
}

const renderCustomPhoto: RenderPhoto<CustomPhoto> = (props) => {
    // access custom attribute via props.photo.customAttribute
};
<PhotoAlbum renderPhoto={renderCustomPhoto} ... />

ClickHandler

type ClickHandler = (event: MouseEvent, photo: Photo, index: number) => void;

PhotoAlbum accepts a click callback handler via the onClick parameter.

<PhotoAlbum onClick={(event, photo, index) => { ... }} ... />

ResponsiveParameter

PhotoAlbum accepts various responsive parameters via ResponsiveParameter type.

type ResponsiveParameter = number | ResponsiveParameterProvider;
type ResponsiveParameterProvider = (containerWidth: number) => number;

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

<PhotoAlbum columns={3} ... />

or as a function of containerWidth

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

ComponentsPropsParameter

type ComponentsPropsParameter = ComponentsProps | ((containerWidth: number) => ComponentsProps);

ComponentsPropsParameter

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.
imagePropsHTMLAttributes<HTMLImageElement>
Additional HTML attributes to be passed to the photo img element.

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'Layout type.
spacingnumberLayout spacing (gaps between photos).
paddingnumberPadding around each photo.
containerWidthnumber
Current photo album container width. Defaults to defaultContainerWidth when rendered server-side.
viewportWidthnumber | undefined
Current viewport width. Defaults to undefined 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.
columnConstraintsColumnConstraints | undefined
Additional column constraints. See ColumnConstraints for details.

RenderPhoto

type RenderPhoto<T extends Photo = Photo> = (props: PhotoProps<T>) => ReactNode;

PhotoAlbum photos can be customized by providing a custom render function via the renderPhoto parameter. The imageProps object contains pre-computed image attributes, and it's generally recommended to use imageProps attributes as a starting point. For instance, imageProps provides CSS-based image dimensions as opposed to layout.width and layout.height that are expressed in pixels.

const renderPhoto: RenderPhoto = ({ imageProps }) => {
    const { src, alt, srcSet, sizes, ...restImageProps } = imageProps;
    return <img src={src} alt={alt} {...(srcSet ? { srcSet, sizes } : null)} {...restImageProps} />;
};
<PhotoAlbum renderPhoto={renderPhoto} ... />

From the performance point of view, it is generally recommended to implement custom render functions either in static context or wrapped with the useCallback hook. However, inline render functions should work perfectly fine under non-frequent repaint conditions.

PhotoProps

PropertyTypeDescription
photoPhoto
Photo object. See Photo for details.
layoutPhotoLayout
Computed photo layout. See PhotoLayout for details.
layoutOptionsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
imageProps
ImgHTMLAttributes<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 will be styled with width and height set to 100%. Use this option when you already sized image wrapper with image dimensions (see wrapperStyle)
wrapperStyleCSSProperties
CSS styles to properly size image wrapper (i.e. <div> wrapper)

PhotoLayout

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

PropertyTypeDescription
widthnumberComputed photo width.
heightnumberComputed photo height.
indexnumber
Photo index in the original photos array.
photoIndexnumberPhoto index in a given row or column.
photosCountnumberTotal number of photos in a given row or column.

RenderContainer

type RenderContainer = (
    props: PropsWithChildren<ContainerProps> & { containerRef?: RefCallback<HTMLDivElement> }
) => ReactNode;

PhotoAlbum container can be customized by providing a custom render function via the renderContainer parameter.

const renderContainer: RenderContainer = ({ containerProps, containerRef, children }: RenderContainerProps) => (
    <div ref={containerRef} {...containerProps}>
        {children}
    </div>
);
<PhotoAlbum renderContainer={renderContainer} ... />

ContainerProps

PropertyTypeDescription
layoutOptionsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
containerProps
HTMLAttributes<HTMLDivElement>
Pre-populated default container attributes (display, flex-wrap, flex-direction and justify-content).

RenderRowContainer

type RenderRowContainer = (props: PropsWithChildren<RowContainerProps>) => ReactNode;

PhotoAlbum row container can be customized by providing a custom render function via the renderRowContainer parameter.

const renderRowContainer: RenderRowContainer = ({ rowContainerProps, children }) => (
    <div {...rowContainerProps}>{children}</div>
);
<PhotoAlbum renderRowContainer={renderRowContainer} ... />

RowContainerProps

PropertyTypeDescription
layoutOptionsRowsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
rowContainerProps
HTMLAttributes<HTMLDivElement>
Pre-populated default row container attributes (display, flex-wrap, flex-direction, justify-content, align-items and margin-bottom).
rowIndexnumberRow number.
rowsCountnumberTotal number of rows.

RenderColumnContainer

type RenderColumnContainer = (props: PropsWithChildren<ColumnContainerProps>) => ReactNode;

PhotoAlbum column container can be customized by providing a custom render function via the renderColumnContainer parameter.

const renderColumnContainer: RenderColumnContainer = ({ columnContainerProps, children }) => (
    <div {...columnContainerProps}>{children}</div>
);
<PhotoAlbum renderColumnContainer={renderColumnContainer} ... />

ColumnContainerProps

PropertyTypeDescription
layoutOptionsColumnsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
columnContainerProps
HTMLAttributes<HTMLDivElement>
Pre-populated default column container attributes (display, flex-wrap, flex-direction, justify-content, align-items and width).
columnIndexnumberColumn number.
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.

ResizeObserverProvider

type ResizeObserverProvider = (
    callback: (entries: ResizeObserverEntry[], observer: ResizeObserver) => void
) => ResizeObserver;

React Photo Album no longer bundles ResizeObserver polyfill as part of the library. If your use case requires you to support some older browsers, you can accomplish this by either installing a global ResizeObserver polyfill or by supplying a ponyfill via the resizeObserverProvider parameter.

<PhotoAlbum resizeObserverProvider={(callback) => {
        // return ResizeObserver instance
    }}
    ...
/>

RowConstraints

PropertyTypeDescription
minPhotosnumber
Minimum number of photos per row in rows layout.
maxPhotosnumber
Maximum number of photos per row in rows layout.

ColumnConstraints

PropertyTypeDescription
minColumnsnumber
Minimum number of columns in masonry or columns layout when there isn't enough photos to fill all the columns.

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