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

Photo

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

LayoutOptions

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

PhotoLayout

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

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

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

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

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

ColumnConstraints

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