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
Property | Type | Description |
---|---|---|
photos | Photo[] | An array of photos to display in the photo album. See Photo for details. |
layout | 'columns' | 'rows' | 'masonry' | Photo album layout type. |
columns | ResponsiveParameter | A number of columns in the columns or masonry layout. See ResponsiveParameter for details. Default responsive value:
|
spacing | ResponsiveParameter | Spacing between images (similar to CSS grid gap). See ResponsiveParameter for details. Default responsive value:
|
padding | ResponsiveParameter | Padding around each image in the photo album. See ResponsiveParameter for details. Default value: 0 |
targetRowHeight | ResponsiveParameter | Target row height in the rows layout. See ResponsiveParameter for details. Default responsive value:
|
rowConstraints | ResponsiveParameter<RowConstraints> | Additional row constraints in the
|
sizes | ResponsiveSizes | Photo album container width at various viewport sizes. See ResponsiveSizes for details. Default value: 100vw |
onClick | ClickHandler | Photo click callback function. See ClickHandler for details. |
breakpoints | number[] | Responsive breakpoints. See ResponsiveBreakpoints for details. |
defaultContainerWidth | number | Default container width in SSR. |
componentsProps | ComponentsPropsParameter | Additional HTML attributes to be passed to the rendered elements. See ComponentsPropsParameter for details. |
renderPhoto | RenderPhoto | Custom photo rendering function. See RenderPhoto for details. |
renderContainer | RenderContainer | Custom container rendering function. See RenderContainer for details. |
renderRowContainer | RenderRowContainer | Custom row container rendering function. See RenderRowContainer for details. |
renderColumnContainer | RenderColumnContainer | Custom column container rendering function. See RenderColumnContainer for details. |
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. |
srcSet | { | Optional array of alternative images to be included in the All images in a given |
images | { | Deprecated. Use |
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
Property | Type | Description |
---|---|---|
index | number | Photo index. |
photo | Photo | Original photo object. |
event | React.MouseEvent | Corresponding 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.
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 | ImgHTMLAttributes<HTMLImageElement> | Additional HTML attributes to be passed to the photo Default: |
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.
Property | Type | Description |
---|---|---|
layout | 'columns' | 'rows' | 'masonry' | Photo album 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. |
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. |
RenderPhoto
PhotoAlbum
photos can be customized via the renderPhoto
render function.
RenderPhoto Props
Property | Type | Description |
---|---|---|
photo | Photo | Photo object. See Photo for details. |
layout | PhotoLayout | Computed photo layout. Please note that
|
layoutOptions | LayoutOptions | PhotoAlbum layout properties. See LayoutOptions for details. |
imageProps | ImgHTMLAttributes<HTMLImageElement> | Pre-populated |
renderDefaultPhoto | (options?: { wrapped?: boolean }) => ReactNode | A callback to render the default photo implementation. If |
wrapperStyle | CSSProperties | 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
Property | Type | Description |
---|---|---|
layout | 'columns' | 'rows' | 'masonry' | Photo album layout type. |
containerProps | HTMLAttributes<HTMLDivElement> | Pre-populated default container attributes ( |
containerRef | RefCallback<HTMLDivElement> | Custom <div/> container ref callback. |
RenderRowContainer
PhotoAlbum
row containers can be customized via the renderRowContainer
render function.
RenderRowContainer Props
Property | Type | Description |
---|---|---|
layoutOptions | RowsLayoutOptions | PhotoAlbum layout properties. See LayoutOptions for details. |
rowIndex | number | Row number. |
rowsCount | number | Total number of rows. |
rowContainerProps | HTMLAttributes<HTMLDivElement> | Pre-populated default row container attributes ( |
RenderColumnContainer
PhotoAlbum
column containers can be customized via the renderColumnContainer
render function.
RenderColumnContainer Props
Property | Type | Description |
---|---|---|
layoutOptions | ColumnsLayoutOptions | PhotoAlbum layout properties. See LayoutOptions for details. |
columnIndex | number | Column index. |
columnsCount | number | Total number of columns. |
columnsGaps | number[] | undefined | Sum of spacings and paddings in each column. |
columnsRatios | number[] | undefined | Width adjustment ratios of each column. columnsRatios property is not provided in the masonry layout. |
columnContainerProps | HTMLAttributes<HTMLDivElement> | Pre-populated default column container attributes ( |
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 in the photo srcSet
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: "992px",
sizes: [
{ viewport: "(max-width: 767px)", size: "calc(100vw - 32px)" },
{ viewport: "(max-width: 1279px)", size: "calc(100vw - 288px)" },
],
}}
// ...
/>
Previous Versions
Are you looking for documentation for one of the previous versions?