https://github.com/pedropalau/react-bnb-gallery
Simple react-based photo gallery inspired by Airbnb image gallery.
https://github.com/pedropalau/react-bnb-gallery
create-react-app create-react-library image-gallery javascript npm-package photo-gallery react reactjs rollup-js
Last synced: 3 months ago
JSON representation
Simple react-based photo gallery inspired by Airbnb image gallery.
- Host: GitHub
- URL: https://github.com/pedropalau/react-bnb-gallery
- Owner: pedropalau
- License: mit
- Created: 2018-12-27T14:42:27.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2026-02-25T06:46:54.000Z (4 months ago)
- Last Synced: 2026-02-25T10:25:48.389Z (4 months ago)
- Topics: create-react-app, create-react-library, image-gallery, javascript, npm-package, photo-gallery, react, reactjs, rollup-js
- Language: JavaScript
- Homepage: https://bnb-gallery.vercel.app/
- Size: 13.1 MB
- Stars: 218
- Watchers: 5
- Forks: 86
- Open Issues: 60
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-github-star - react-bnb-gallery - based photo gallery inspired by Airbnb image gallery. | pedropalau | 206 | (JavaScript)
README
Friendly, customizable and accessible-ready simple photo gallery based on React.
------
## Install
You can install [react-bnb-gallery](https://www.npmjs.com/package/react-bnb-gallery) from [npm](https://www.npmjs.com/).
```bash
npm install react-bnb-gallery
```
```bash
yarn add react-bnb-gallery
```
```bash
pnpm add react-bnb-gallery
```
Don't forget to import the stylesheet:
```js
import 'react-bnb-gallery/dist/style.css';
```
## Usage
```jsx
import React, { useState } from 'react';
import ReactBnbGallery from 'react-bnb-gallery';
import 'react-bnb-gallery/dist/style.css';
const PHOTOS = [
{
photo: 'https://example.com/photo1.jpg',
thumbnail: 'https://example.com/photo1-thumb.jpg',
caption: 'Photo 1',
subcaption: 'Author name or location',
},
{
photo: 'https://example.com/photo2.jpg',
thumbnail: 'https://example.com/photo2-thumb.jpg',
caption: 'Photo 2',
},
];
export default function App() {
const [open, setOpen] = useState(false);
return (
<>
setOpen(true)}>Open Gallery
setOpen(false)}
/>
>
);
}
```
## Props
### ``
| Prop | Type | Default | Description |
|---|---|---|---|
| `photos` | `Photo[] \| string[]` | — | **Required.** Array of photo objects or plain URL strings. |
| `onClose` | `() => void` | — | **Required.** Callback fired when the gallery is closed. |
| `show` | `boolean` | `false` | Controls whether the gallery modal is visible. |
| `activePhotoIndex` | `number` | `0` | Index of the photo shown on open. |
| `showThumbnails` | `boolean` | `true` | Show the thumbnail strip. |
| `keyboard` | `boolean` | `true` | Enable keyboard navigation (arrow keys, Escape). |
| `wrap` | `boolean` | `true` | Cycle continuously through photos instead of hard stops. |
| `preloadSize` | `number` | `1` | Number of adjacent photos to preload. |
| `opacity` | `number` | `1` | Background overlay opacity (0–1). |
| `backgroundColor` | `string` | `'#000'` | Background color of the gallery. |
| `zIndex` | `number` | — | CSS `z-index` for the modal. |
| `phrases` | `object` | — | Custom labels for UI strings (e.g. close button, counters). |
| `activePhotoPressed` | `() => void` | — | Callback fired when the active photo is clicked. |
| `nextButtonPressed` | `() => void` | — | Callback fired when the next button is pressed. |
| `prevButtonPressed` | `() => void` | — | Callback fired when the previous button is pressed. |
| `leftKeyPressed` | `() => void` | — | Callback fired when the left arrow key is pressed. |
| `rightKeyPressed` | `() => void` | — | Callback fired when the right arrow key is pressed. |
### `Photo` object
| Field | Type | Description |
|---|---|---|
| `photo` | `string` | **Required.** URL of the full-size image. |
| `thumbnail` | `string` | URL of the thumbnail image (recommended: `100×67px`). |
| `caption` | `string` | Short description shown below the photo. |
| `subcaption` | `string` | Secondary description (e.g. author or location). |
| `number` | `number` | Override the displayed photo number. |
## Live Demo
The demo and documentation are available at the [docs site](https://peterpalau.github.io/react-bnb-gallery/). To run them locally:
```bash
pnpm docs:dev
```
## License
This package has been released under the [MIT Licence](https://raw.githubusercontent.com/peterpalau/react-bnb-gallery/master/LICENSE).
## Updates
To view the full changelog visit [CHANGELOG.md](https://github.com/peterpalau/react-bnb-gallery/blob/master/CHANGELOG.md).
## Migration to 2.0.0
### React support
- `react-bnb-gallery@2.x` requires `react` and `react-dom` `^18 || ^19`.
- React 15/16 are no longer supported.
### Breaking changes
- Preload images are now correctly returned/rendered by the gallery preload path.
- Gallery and caption controls now react correctly when the `photos` prop changes at runtime.
- The `phrases` prop-type shape is now generated from the keys of the provided object.
### Deprecation policy
Deprecated APIs receive warnings and documentation during `2.x`, then are removed in the next major release unless doing so would be unsafe.
## Contributing
If you're interested in contributing please read the [contributing docs](https://github.com/peterpalau/react-bnb-gallery/blob/master/CONTRIBUTING.md) **before submitting a pull request**.