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
Property | Type | Description |
---|---|---|
photos | Photo [] | 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 Default responsive value:
| |
spacing | Spacing between images (similar to CSS grid gap). Default responsive value:
| |
padding | Padding around each image in the photo album. Default value: 0 | |
targetRowHeight | Target row height in the Default responsive value:
| |
rowConstraints | Additional row constraints. | |
columnConstraints | Additional column constraints. | |
sizes | Photo album width at various viewport sizes. Default value: 100vw | |
onClick | Photo click callback function. | |
breakpoints | number[] | Responsive breakpoints. See ResponsiveBreakpoints for details. |
defaultContainerWidth | number | Default container width to be used in the server-side render. Default value: 800 |
componentsProps | Additional HTML attributes to be passed to the rendered elements. | |
renderPhoto | Custom photo rendering function. | |
renderContainer | Custom container rendering function. | |
renderRowContainer | Custom row container rendering function | |
renderColumnContainer | Custom column container rendering function | |
resizeObserverProvider | ResizeObserver factory to be used when global ResizeObserver is unavailable. |
Photo
Property | Type | Description |
---|---|---|
key | string | Optional key attribute. |
src | string | Image source. |
width | number | Image width in pixels. |
height | number | Image height in pixels. |
alt | string | Optional image alt attribute. |
title | string | 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
Property | Type | Description |
---|---|---|
containerProps | HTMLAttributes<HTMLDivElement> | Additional HTML attributes to be passed to the outer container div element. |
rowContainerProps | HTMLAttributes<HTMLDivElement> | Additional HTML attributes to be passed to the row container div element. |
columnContainerProps | HTMLAttributes<HTMLDivElement> | Additional HTML attributes to be passed to the column container div element. |
imageProps | HTMLAttributes<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.Property | Type | Description |
---|---|---|
layout | 'columns' | 'rows' | 'masonry' | Layout type. |
spacing | number | Layout spacing (gaps between photos). |
padding | number | Padding around each photo. |
containerWidth | number | Current photo album container width. Defaults to defaultContainerWidth when rendered server-side. |
viewportWidth | number | undefined | Current viewport width. Defaults to undefined when rendered server-side. |
onClick | ClickHandler | undefined | Photo click handler. See ClickHandler for details. |
sizes | ResponsiveSizes | undefined | PhotoAlbum size at various viewport sizes. See ResponsiveSizes for details. |
columns | number | undefined | Number of columns in columns or masonry layout. |
targetRowHeight | number | undefined | Target row height in rows layout. |
rowConstraints | RowConstraints | undefined | Additional row constraints. See RowConstraints for details. |
columnConstraints | ColumnConstraints | 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
Property | Type | Description |
---|---|---|
photo | Photo | Photo object. See Photo for details. |
layout | PhotoLayout | Computed photo layout. See PhotoLayout for details. |
layoutOptions | LayoutOptions | 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 ) |
wrapperStyle | CSSProperties | 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.
Property | Type | Description |
---|---|---|
width | number | Computed photo width. |
height | number | Computed photo height. |
index | number | Photo index in the original photos array. |
photoIndex | number | Photo index in a given row or column. |
photosCount | number | Total 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
Property | Type | Description |
---|---|---|
layoutOptions | LayoutOptions | 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
Property | Type | Description |
---|---|---|
layoutOptions | RowsLayoutOptions | 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 ). |
rowIndex | number | Row number. |
rowsCount | number | Total 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
Property | Type | Description |
---|---|---|
layoutOptions | ColumnsLayoutOptions | 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 ). |
columnIndex | number | Column number. |
columnsCount | number | Total number of columns. |
columnsGaps | number[] | undefined | Sum of spacings and paddings in each column. columnsGaps property is not provided in the masonry layout. |
columnsRatios | number[] | 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
Property | Type | Description |
---|---|---|
minPhotos | number | Minimum number of photos per row in rows layout. |
maxPhotos | number | Maximum number of photos per row in rows layout. |
ColumnConstraints
Property | Type | Description |
---|---|---|
minColumns | number | 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)" },
],
}}
...
/>