React Photo Album

React Photo Album allows full UI customization by providing custom render functions via the render prop. Each function receives the default element's props as the first argument (typically including style and className). Some functions also receive a second argument representing the photo rendering context.

Photo Rendering Context

When the second argument is provided, it contains:

• photo: The Photo object.
• index: The index of the photo in the original photos array.
• width: Rendered photo width in pixels.
• height: Rendered photo height in pixels.

Available Render Functions

• container: Customizes the main album div. Must forward the ref attribute to the underlying element.
• track: Customizes row/column containers.
• wrapper: Customizes the image wrapper (used when photos are not clickable).
• link: Customizes the link element (used when a photo has an href).
• button: Customizes the button element (used when an onClick callback is provided).
• image: Customizes the <img> element.
• extras: Renders custom markup immediately after each image (useful for absolute positioned icons).
• photo: A complete override that replaces wrapper, link, button, image, and extras. It only receives onClick in the first argument.

// Example: Customizing the container (must forward ref)
<RowsPhotoAlbum
  photos={photos}
  render={{
    container: ({ ref, ...rest }) => <div ref={ref} {...rest} />,
  }}
/>

// Example: Adding custom icons via extras
<RowsPhotoAlbum
  photos={photos}
  render={{
    extras: (_, { photo, index }) => (
      <FavoriteIcon photo={photo} index={index} />
    ),
  }}
/>

// Example: Complete photo override
<RowsPhotoAlbum
  photos={photos}
  render={{
    photo: ({ onClick }, { photo, width, height }) => (
      <CustomPhoto
        photo={photo}
        width={width}
        height={height}
        onClick={onClick}
      />
    ),
  }}
/>

By default, React Photo Album produces empty markup during SSR because the container width is unknown, which can cause Content Layout Shift (CLS) upon hydration. You can use one of the following three strategies to mitigate this:

1. Default Container Width: Specify defaultContainerWidth to render markup on the server. This is ideal for fixed-width containers (e.g., sidebars) but may cause layout shift if the client-side width differs.
2. Skeleton: Provide a fallback UI via the skeleton prop. This reserves space on the page to prevent content jumping, though images won't start downloading until after hydration unless you manually add prefetch links.
3. Visibility Hidden: Render the album with visibility: hidden on the server using componentsProps. This prevents layout flashes and allows the browser to start downloading images before hydration.

// 1. Default Container Width
<RowsPhotoAlbum photos={photos} defaultContainerWidth={800} />

// 2. Skeleton
<RowsPhotoAlbum
  photos={photos}
  skeleton={<div style={{ width: "100%", minHeight: 800 }} />}
/>

// 3. Visibility Hidden
<RowsPhotoAlbum
  photos={photos}
  defaultContainerWidth={800}
  componentsProps={(containerWidth) =>
    containerWidth === undefined
      ? { container: { style: { visibility: "hidden" } } }
      : {}
  }
/>

If you are developing the library and want to test changes in real-time within an example project, follow these steps to link the local library to an example:

1. Build the library: In the root of the repository, install dependencies and start the library build script.

   npm install
   npm run start

2. Link to an example: Navigate to the desired example directory, install its dependencies, and use npm link to point to the local library source.

   cd <example>
   npm install
   npm link ../..
   npm run dev

3. Cleanup: To revert the example to use the published version of the library instead of your local link, run:

   cd <example>
   npm unlink --no-save react-photo-album
   npm unlink -g react-photo-album
   npm install

# Build the library
npm install
npm run start

# Link to an example
cd <example>
npm install
npm link ../..
npm run dev

# Cleanup
cd <example>
npm unlink --no-save react-photo-album
npm unlink -g react-photo-album
npm install