Comparison with the original library

[oyeanuj]

Hey @igordanchenko, thanks so much for creating this library especially as the old one was no longer being maintained. I was curious if there are changes to the library from the old one that we should be aware of as we switch over? Any change in features/functionality?

[igordanchenko]

@oyeanuj,

The short answer to your question is there are a lot of changes. While react-photo-album was built on the foundation of react-photo-gallery and supports all of its original features, it's not a drop-in replacement as the API diverged quite noticeably. Your migration steps will vary depending on what react-photo-gallery API features you were using.

I'll cover some of the most significant changes below, and I'll look into putting together a comprehensive migration guide on the website if this question comes up frequently. In the meantime, feel free to read through the API documentation, as I'm sure you'll find most answers to your questions over there.

First of all, react-photo-album addressed numerous annoying issues that were present in react-photo-gallery@8.0.0:

• eliminated hard peer dependency on React 16, so you no longer have to force-install the library (react-photo-album is compatible with React 16.14.0, React 17, and React 18 once it's released)
• eliminated React warning about the useLayoutEffect hook in SSR
• implemented proper SSR support (react-photo-gallery pretended to be SSR-compatible but rendered nothing in SSR)
• eliminated annoying flickering during window resize
• fixed several non-obvious bugs in the justified gallery layout algorithm

In terms of features, react-photo-album supports both original image layouts (justified horizontal gallery and masonry), so you can expect them to look pretty much identical. And on top of that, react-photo-album introduced a brand new columns layout (you can find an example on the documentation website).

In terms of API changes, here are the most significant ones:

1. The layout property is required in react-photo-album. The direction property used to be optional in react-photo-gallery and defaulted to row. You are now required to define the desired layout in react-photo-album explicitly.
2. The photos array items no longer accept srcSet and sizes attributes. Instead, you can provide alternative images via the images array, and react-photo-album will generate srcSet and sizes automatically on the fly.
3. Custom renderPhoto function props are structured entirely differently. If you were using the renderImage function, make sure you read through the renderPhoto documentation. While react-photo-gallery used to size images in pixels, react-photo-album uses calculated CSS styles by default. You can still use width/height expressed in pixels if you prefer to, but CSS styling allows for new exciting features like responsive breakpoints.
4. The onClick function props are also structured differently. It no longer provides index, previous, and next props as all of them can be derived from the original photos array.
5. The margin prop was replaced with spacing. The margin prop used to add blank space around all images and the side-effect of this approach was that the outmost images weren't flush to the gallery edges. Hence, the workaround was to add a negative margin to the gallery container. This workaround is no longer necessary as the spacing prop works as CSS grid spacing and doesn't add blank space to the gallery edges.

Okay, these are the most noticeable changes off the top of my head, so I'm going to stop here. I'll update this discussion with the link to the migration guide when it's ready.

p.s. If you like this project and end up using it, please consider giving it a star here on GitHub 🙌