Registry / web-framework / react-photo-album

react-photo-album

library3.6.0jsnpmunverified

React Photo Album is a responsive React component designed for building dynamic photo galleries, currently at version 3.6.0. It offers three distinct layout options: rows, columns, and masonry, each powered by sophisticated dynamic programming algorithms to ensure optimal arrangement and visual balance. Its rows layout, inspired by the Knuth and Plass algorithm, minimizes deviations from a target row height, preventing stretched images or awkward last rows. The columns layout dynamically balances content, while masonry places photos into the shortest column. The library is actively maintained with regular updates and emphasizes performance, SSR compatibility, built-in TypeScript definitions, and automatic responsive image handling. It serves as a re-engineered alternative to `react-photo-gallery`, supporting React 18+ and Node 18+ and requiring modern ESM-compatible bundlers.

web-framework

npm install react-photo-album

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · REACT-PHOTO-ALBUM

react-photo-album

web-frameworkjavascriptv3.6.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PhotoAlbum

✓ import PhotoAlbum from 'react-photo-album';

✗ import { PhotoAlbum } from 'react-photo-album'; const PhotoAlbum = require('react-photo-album');

PhotoAlbum is the aggregate default export, bundling all three layouts. Use 'import PhotoAlbum from...' for this component. For layout-specific components, use named imports. Since v3, the library is ESM-only, so CommonJS `require` will fail.

RowsPhotoAlbum

✓ import { RowsPhotoAlbum } from 'react-photo-album';

✗ import RowsPhotoAlbum from 'react-photo-album';

RowsPhotoAlbum is a named export for the rows-specific layout component. Similar named exports exist for ColumnsPhotoAlbum and MasonryPhotoAlbum.

Photo

✓ import type { Photo } from 'react-photo-album';

✗ import { Photo } from 'react-photo-album';

Photo is a TypeScript type definition for photo objects, typically imported using `import type` for clarity and to avoid bundling issues with value imports.

CSS Styles

✓ import 'react-photo-album/styles.css'; // For PhotoAlbum (3-in-1 component) import 'react-photo-album/rows.css'; // For RowsPhotoAlbum

✗ /* No explicit CSS import */

Since v3, a CSS stylesheet is required. If using the aggregate PhotoAlbum component, import 'react-photo-album/styles.css'. For layout-specific components (e.g., RowsPhotoAlbum), import the corresponding CSS (e.g., 'react-photo-album/rows.css'). Omitting this import will result in unstyled layouts.

Demonstrates a basic responsive photo gallery using the RowsPhotoAlbum component with dynamic photo data, custom row height, spacing, and a click handler.

import { RowsPhotoAlbum } from 'react-photo-album'; import 'react-photo-album/rows.css'; const photos = [ { src: 'https://images.unsplash.com/photo-1594904005118-a6825c9b2e2d', width: 800, height: 600, alt: 'A scenic landscape' }, { src: 'https://images.unsplash.com/photo-1506157788612-fc905187e5cf', width: 1600, height: 900, alt: 'City skyline at night' }, { src: 'https://images.unsplash.com/photo-1549721727-b089b2f6c0f0', width: 1200, height: 800, alt: 'Close-up of a flower' }, { src: 'https://images.unsplash.com/photo-1510798083980-0a14d5f479d2', width: 900, height: 1200, alt: 'Person hiking on a mountain' }, { src: 'https://images.unsplash.com/photo-1509343206535-c3f2b6a2f8d0', width: 1000, height: 750, alt: 'Abstract art piece' } ]; export default function Gallery() { return ( <RowsPhotoAlbum photos={photos} targetRowHeight={250} spacing={8} onClick={({ index }) => console.log(`Clicked photo at index: ${index}`)} /> ); }

Debug

Known issues

breakingNode.js and React Version Upgrade: `react-photo-album` v3.0.0 and later require Node.js 18+ and React 18+. Projects on older Node.js or React versions must upgrade their environment.

fix

Upgrade your Node.js installation to v18 or newer, and your React installation to v18 or newer. Ensure `@types/react` is also updated if using TypeScript.

affects: >=3.0.0

breakingESM-only and Modern Bundler Requirement: Since v3.0.0, the library is distributed as ESM-only. It requires a modern, ESM-compatible bundler (e.g., Vite, Webpack 5 with appropriate configuration). CommonJS environments or older bundlers will encounter import errors.

fix

Configure your project's bundler to correctly handle ESM imports, or ensure you are using a modern build toolchain. Avoid `require()` statements for this package.

affects: >=3.0.0

breakingCSS Stylesheet is Required: Starting with v3.0.0, CSS-in-JS styling was replaced with external CSS stylesheets. Developers must explicitly import the relevant CSS file for the chosen layout. Omitting this will result in an unstyled or broken layout.

fix

For the aggregate PhotoAlbum component, add `import 'react-photo-album/styles.css';`. For layout-specific components (e.g., RowsPhotoAlbum), add `import 'react-photo-album/rows.css';`.

affects: >=3.0.0

breakingChanged Render Prop API: In v3.0.0, several `render` props (e.g., `renderContainer`, `renderPhoto`) and `componentsProps` were replaced with more granular and modern APIs like `render.container`, `render.image`, `componentsProps.container`, etc.

fix

Consult the official documentation for the updated `render` functions and `componentsProps` API. Update custom rendering logic to use the new prop names.

affects: >=3.0.0

gotchaPhotos Must Have Valid Dimensions: All `Photo` objects provided to the component must include `width` and `height` properties, and these values must be greater than zero. Supplying zero-dimension photos can lead to corrupted or empty layouts.

fix

Ensure all `photo` objects in the `photos` array have valid `width` and `height` properties (e.g., `{ src: '...', width: 800, height: 600 }`).

affects: >=3.0.0

gotchaUnique Keys for Photos: Providing an array of photos with identical `id` or `key` properties can lead to React key collision warnings and potential rendering issues, especially when adding or removing photos.

fix

Ensure each `photo` object in the `photos` array has a unique `id` property, or provide a custom `key` prop to the PhotoAlbum component that guarantees uniqueness.

affects: >=3.5.1

Errors

Common errors & fixes

ReferenceError: require is not defined (for 'react-photo-album')

Attempting to use CommonJS `require()` syntax in an ESM-only environment.

fix

Change `const PhotoAlbum = require('react-photo-album');` to `import PhotoAlbum from 'react-photo-album';` (or specific named imports if applicable).

Layout appears unstyled, photos stacked, or missing visual formatting.

The required CSS stylesheet for the chosen layout has not been imported.

fix

Add the appropriate CSS import: `import 'react-photo-album/styles.css';` for the aggregate `PhotoAlbum` component, or `import 'react-photo-album/rows.css';` (or `columns.css`/`masonry.css`) for layout-specific components.

Warning: Each child in a list should have a unique 'key' prop.

Multiple `Photo` objects in the `photos` array have identical `id` properties, leading to React key collision.

fix

Ensure that each object in the `photos` array has a unique `id` property, or explicitly provide a unique `key` prop for each photo object. This issue was specifically addressed for duplicate photos in v3.5.1.

Layout looks corrupted, some photos are missing, or calculation errors occur.

One or more `Photo` objects provided to the component have `width` or `height` properties set to zero or an invalid value.

fix

Verify that all `Photo` objects in your `photos` array have valid `width` and `height` numerical values greater than zero.

Upgrade

Version history

3.6.0latest on npm

Audit

Dependencies

reactrequiredReact is the core framework for this component. Required for rendering UI.

@types/reactoptionalTypeScript type definitions for React, essential for TypeScript projects.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/igordanchenko/react-photo-album ↗

packagehttps://www.npmjs.com/package/react-photo-album ↗

homepagehttps://react-photo-album.com ↗