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 srcSet instead. |
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 |
rowContainerProps | HTMLAttributes<HTMLDivElement> | Additional HTML attributes to be passed to the row container |
columnContainerProps | HTMLAttributes<HTMLDivElement> | Additional HTML attributes to be passed to the column container |
imageProps | ImgHTMLAttributes<HTMLImageElement> | Additional HTML attributes to be passed to the photo Default: { loading: "lazy", decoding: "async"} |
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 |
onClick | ClickHandler | undefined | Photo click handler. See ClickHandler for details. |
sizes | ResponsiveSizes | undefined |
|
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 |
|
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. |
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. Please note that you must pass the containerRef
ref to your
container element (see example).
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 |
|
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 |
|
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. |
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?