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
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. See RowConstraints for details.
columnConstraintsResponsiveParameter​<ColumnConstraints>
Additional column constraints. See ColumnConstraints for details.
sizesResponsiveSizes

Photo album 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 to be used in the server-side render. defaultContainerWidth value affects all responsive parameters that depend on containerWidth.

Default value: 800

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.

resizeObserverProviderResizeObserverProvider

ResizeObserver factory to be used when global ResizeObserver is unavailable. See ResizeObserverProvider 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.

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.
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 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.
containerPropsHTMLAttributes​<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.
rowContainerPropsHTMLAttributes​<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 = ({ columnContainerProps, children }) => (
    <div {...columnContainerProps}>{children}</div>
);
<PhotoAlbum
    renderColumnContainer={renderColumnContainer}
    // ...
/>

ColumnContainerProps

PropertyTypeDescription
layoutOptionsColumnsLayoutOptions
PhotoAlbum layout properties. See LayoutOptions for details.
columnContainerPropsHTMLAttributes​<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[] | undefinedWidth 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)" },
        ],
    }}
    // ...
/>