{"id":15208,"library":"react-photo-album","title":"React Photo Album","description":"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.","status":"active","version":"3.6.0","language":"javascript","source_language":"en","source_url":"https://github.com/igordanchenko/react-photo-album","tags":["javascript","react","image","photo","album","gallery","masonry","photo album","photo gallery","typescript"],"install":[{"cmd":"npm install react-photo-album","lang":"bash","label":"npm"},{"cmd":"yarn add react-photo-album","lang":"bash","label":"yarn"},{"cmd":"pnpm add react-photo-album","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"React is the core framework for this component. Required for rendering UI.","package":"react","optional":false},{"reason":"TypeScript type definitions for React, essential for TypeScript projects.","package":"@types/react","optional":true}],"imports":[{"note":"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.","wrong":"import { PhotoAlbum } from 'react-photo-album';\nconst PhotoAlbum = require('react-photo-album');","symbol":"PhotoAlbum","correct":"import PhotoAlbum from 'react-photo-album';"},{"note":"RowsPhotoAlbum is a named export for the rows-specific layout component. Similar named exports exist for ColumnsPhotoAlbum and MasonryPhotoAlbum.","wrong":"import RowsPhotoAlbum from 'react-photo-album';","symbol":"RowsPhotoAlbum","correct":"import { RowsPhotoAlbum } from 'react-photo-album';"},{"note":"Photo is a TypeScript type definition for photo objects, typically imported using `import type` for clarity and to avoid bundling issues with value imports.","wrong":"import { Photo } from 'react-photo-album';","symbol":"Photo","correct":"import type { Photo } from 'react-photo-album';"},{"note":"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.","wrong":"/* No explicit CSS import */","symbol":"CSS Styles","correct":"import 'react-photo-album/styles.css'; // For PhotoAlbum (3-in-1 component)\nimport 'react-photo-album/rows.css'; // For RowsPhotoAlbum"}],"quickstart":{"code":"import { RowsPhotoAlbum } from 'react-photo-album';\nimport 'react-photo-album/rows.css';\n\nconst photos = [\n  { src: 'https://images.unsplash.com/photo-1594904005118-a6825c9b2e2d', width: 800, height: 600, alt: 'A scenic landscape' },\n  { src: 'https://images.unsplash.com/photo-1506157788612-fc905187e5cf', width: 1600, height: 900, alt: 'City skyline at night' },\n  { src: 'https://images.unsplash.com/photo-1549721727-b089b2f6c0f0', width: 1200, height: 800, alt: 'Close-up of a flower' },\n  { src: 'https://images.unsplash.com/photo-1510798083980-0a14d5f479d2', width: 900, height: 1200, alt: 'Person hiking on a mountain' },\n  { src: 'https://images.unsplash.com/photo-1509343206535-c3f2b6a2f8d0', width: 1000, height: 750, alt: 'Abstract art piece' }\n];\n\nexport default function Gallery() {\n  return (\n    <RowsPhotoAlbum\n      photos={photos}\n      targetRowHeight={250}\n      spacing={8}\n      onClick={({ index }) => console.log(`Clicked photo at index: ${index}`)}\n    />\n  );\n}","lang":"typescript","description":"Demonstrates a basic responsive photo gallery using the RowsPhotoAlbum component with dynamic photo data, custom row height, spacing, and a click handler."},"warnings":[{"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.","message":"Node.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.","severity":"breaking","affected_versions":">=3.0.0"},{"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.","message":"ESM-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.","severity":"breaking","affected_versions":">=3.0.0"},{"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';`.","message":"CSS 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Consult the official documentation for the updated `render` functions and `componentsProps` API. Update custom rendering logic to use the new prop names.","message":"Changed 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.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure all `photo` objects in the `photos` array have valid `width` and `height` properties (e.g., `{ src: '...', width: 800, height: 600 }`).","message":"Photos 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"Unique 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.","severity":"gotcha","affected_versions":">=3.5.1"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change `const PhotoAlbum = require('react-photo-album');` to `import PhotoAlbum from 'react-photo-album';` (or specific named imports if applicable).","cause":"Attempting to use CommonJS `require()` syntax in an ESM-only environment.","error":"ReferenceError: require is not defined (for 'react-photo-album')"},{"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.","cause":"The required CSS stylesheet for the chosen layout has not been imported.","error":"Layout appears unstyled, photos stacked, or missing visual formatting."},{"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.","cause":"Multiple `Photo` objects in the `photos` array have identical `id` properties, leading to React key collision.","error":"Warning: Each child in a list should have a unique 'key' prop."},{"fix":"Verify that all `Photo` objects in your `photos` array have valid `width` and `height` numerical values greater than zero.","cause":"One or more `Photo` objects provided to the component have `width` or `height` properties set to zero or an invalid value.","error":"Layout looks corrupted, some photos are missing, or calculation errors occur."}],"ecosystem":"npm"}