\n\nReact Photo Album is a responsive photo gallery component for React. React Photo\nAlbum supports rows, columns, and masonry layouts. Inspired by\n[react-photo-gallery](https://github.com/neptunian/react-photo-gallery),\nre-engineered from the ground up.\n\n## Overview\n\n- **Built for React:** works with React 18+\n- **SSR friendly:** produces server-side rendered markup that looks\n pixel-perfect on the client even before hydration\n- **Responsive images:** responsive images with automatic resolution switching\n are supported out of the box\n- **Feature-packed:** supports 3 layout options (rows, columns, and masonry),\n responsive images, custom data attributes, and is fully configurable and\n customizable\n- **TypeScript:** type definitions come built-in with the package\n- **Performance:** built with performance in mind to support large photo albums\n\n## Layouts\n\n### Rows\n\n\n\n### Columns\n\n\n\n### Masonry\n\n\n\n## Documentation\n\n[https://react-photo-album.com/documentation](https://react-photo-album.com/documentation)\n\n## Examples\n\n[https://react-photo-album.com/examples](https://react-photo-album.com/examples)\n\n## Changelog\n\n[https://github.com/igordanchenko/react-photo-album/releases](https://github.com/igordanchenko/react-photo-album/releases)\n\n## Installation\n\n```shell\nnpm install react-photo-album\n```\n\n## Requirements\n\n- React 18+\n- Node 18+\n- modern ESM-compatible bundler\n\n## Minimal Setup Example\n\n```tsx\nimport { RowsPhotoAlbum } from \"react-photo-album\";\nimport \"react-photo-album/rows.css\";\n\nconst photos = [\n { src: \"/image1.jpg\", width: 800, height: 600 },\n { src: \"/image2.jpg\", width: 1600, height: 900 },\n];\n\nexport default function Gallery() {\n return ;\n}\n```\n\n## How It Works\n\n### Rows Layout\n\nRows layout fills the container space by arranging photos into rows that are\nsimilar in height, with the height of each row being as close to the\n`targetRowHeight` as possible. This layout is inspired by the Knuth and Plass\nline-breaking algorithm and uses dynamic programming to find optimal row breaks\nin a DAG (directed acyclic graph) where photo indices are nodes and each\npossible row is an edge connecting its first and last photo. The cost of each\nedge is a weighted squared deviation from the `targetRowHeight`. This algorithm\nproduces rows that are similar in height and photos that are not stretched or\nabnormally shrunk (as happens in a naive implementation). It solves the issue of\npanoramas shrinking rows, stragglers, or stretched images in the last row.\n\n### Columns Layout\n\nColumns layout fills the container space by arranging photos into a predefined\nnumber of columns, determined by the `columns` parameter. This layout uses a\ndynamic programming algorithm to find the optimal partition of photos into the\nspecified number of groups (columns) that produces the most balanced layout.\nColumn widths are then adjusted proportionally based on their content's aspect\nratios so that all columns render at equal height.\n\n### Masonry Layout\n\nMasonry layout arranges photos into columns of equal width by placing each photo\ninto the shortest column. This layout does not fill the container space flush to\nits bottom edge, but the columns end up being as close in height to each other\nas possible.\n\n### Responsive Images\n\nReact Photo Album can automatically produce `sizes` and `srcset` image\nattributes. In the case of SSR, React Photo Album includes `sizes` and `srcset`\nimage attributes in the server-rendered markup, allowing browsers to pick images\nof the most appropriate resolution depending on the end-user viewport size. To\nutilize images with automatic resolution switching, provide images of different\nresolutions in the photo `srcSet` attribute. To further improve app\nresponsiveness and bandwidth utilization, you can specify the `sizes` prop that\ndescribes the width of the photo album in various viewports.\n\n```tsx\nimport { RowsPhotoAlbum } from \"react-photo-album\";\nimport \"react-photo-album/rows.css\";\n\nconst photos = [\n {\n src: \"/image1_800x600.jpg\",\n width: 800,\n height: 600,\n srcSet: [\n { src: \"/image1_400x300.jpg\", width: 400, height: 300 },\n { src: \"/image1_200x150.jpg\", width: 200, height: 150 },\n ],\n },\n {\n src: \"/image2_1600x900.jpg\",\n width: 1600,\n height: 900,\n srcSet: [\n { src: \"/image2_800x450.jpg\", width: 800, height: 450 },\n { src: \"/image2_400x225.jpg\", width: 400, height: 225 },\n ],\n },\n];\n\nexport default function Gallery() {\n return (\n \n );\n}\n```\n\n### SSR\n\nReact Photo Album extensively uses CSS flexbox and CSS `calc` functions to\ncalculate images' dimensions on the client. Thanks to this approach, server-side\nrendered markup looks pixel-perfect on the client even before hydration. To\nenable server-side rendering, specify the `defaultContainerWidth` prop.\nOtherwise, React Photo Album produces empty markup on the server and renders on\nthe client only after hydration. Please note that unless your photo album is of\nconstant width that always matches the `defaultContainerWidth` value, you will\nmost likely see a layout shift immediately after hydration. Alternatively, you\ncan provide a fallback skeleton in the `skeleton` prop that will be rendered in\nSSR and swapped with the actual photo album markup after hydration. Please also\nrefer to the\n[Server-Side Rendering]()\ndocumentation for a comprehensive list of available solutions.\n\n## Sponsors\n\nThis project is supported by the following companies, organizations, and\nindividuals who help make its continued development and maintenance possible.\n\n
![\"\"](\".github/assets/logo.webp\"){kind=logo}
\n![\"Sponsors\"](\"https://cdn.jsdelivr.net/gh/igordanchenko/sponsors/sponsors.svg\")
\n \n