Options

A full reference of all available props to configure and customize the gallery.

Gallery props

Prop	Type	Default
`activePhotoIndex`	`number`	`0`
`activePhotoPressed`	`() => void`	`undefined`
`backgroundColor`	`string`	`'rgba(0,0,0,1)'`
`direction`deprecated	`string`	`'forwards'`
`keyboard`	`boolean`	`true`
`leftKeyPressed`	`() => void`	`undefined`
`light`	`boolean`	`false`
`nextButtonPressed`	`() => void`	`undefined`
`onClose`	`() => void`	`undefined`
`opacity`	`number`	`1`
`photos`	`string \| GalleryPhoto \| Array<...>`	`[]`
`phrases`	`GalleryPhrases`	`{...}`
`preloadSize`	`number`	`5`
`prevButtonPressed`	`() => void`	`undefined`
`rightKeyPressed`	`() => void`	`undefined`
`show`	`boolean`	`false`
`showThumbnails`	`boolean`	`true`
`wrap`	`boolean`	`false`
`zIndex`	`number`	`2000`

activePhotoIndex

The index of the photo to display when the gallery opens. Useful when opening from a specific item in a photo grid.

<ReactBnbGallery
  show={open}
  photos={photos}
  activePhotoIndex={2}
  onClose={() => setOpen(false)}
/>

activePhotoPressed

Callback fired when the user clicks on the currently active photo.

<ReactBnbGallery
  show={open}
  photos={photos}
  activePhotoPressed={(index) => console.log('Pressed:', index)}
  onClose={() => setOpen(false)}
/>

backgroundColor

Sets the background color of the gallery overlay. Accepts any valid CSS color value — hex, rgb, rgba, hsl, etc.

<ReactBnbGallery
  show={open}
  photos={photos}
  backgroundColor="rgba(15, 15, 30, 0.95)"
  onClose={() => setOpen(false)}
/>

direction

deprecated

Controls the animation direction when navigating between photos. This prop is deprecated and will be removed in the next major version — avoid using it in new code.

keyboard

When enabled, the gallery responds to keyboard arrow key navigation and the Escape key to close. Disable if you need to handle keyboard events yourself.

<ReactBnbGallery
  show={open}
  photos={photos}
  keyboard={false}
  onClose={() => setOpen(false)}
/>

leftKeyPressed

Callback fired when the left arrow key is pressed. Can be used to sync external state alongside the built-in navigation.

<ReactBnbGallery
  show={open}
  photos={photos}
  leftKeyPressed={() => console.log('Left key pressed')}
  onClose={() => setOpen(false)}
/>

light

Enables a light color scheme for the gallery UI. By default the gallery uses a dark theme. Set to true to switch to a light background with dark controls.

<ReactBnbGallery
  show={open}
  photos={photos}
  light
  onClose={() => setOpen(false)}
/>

nextButtonPressed

Callback fired when the next → control button is clicked.

<ReactBnbGallery
  show={open}
  photos={photos}
  nextButtonPressed={() => console.log('Next clicked')}
  onClose={() => setOpen(false)}
/>

onClose

Called when the gallery requests to be closed — via the close button or pressing Escape. Use this to update your state and unmount the gallery.

const [open, setOpen] = useState(false);

<ReactBnbGallery
  show={open}
  photos={photos}
  onClose={() => setOpen(false)}
/>

opacity

Controls the opacity of the gallery overlay. Accepts values between 0 (invisible) and 1 (fully opaque).

<ReactBnbGallery
  show={open}
  photos={photos}
  opacity={0.9}
  onClose={() => setOpen(false)}
/>

photos

The photos to display. Accepts a single URL string, a single photo object, or an array of either — including mixed arrays.

// Single URL
<ReactBnbGallery show={open} photos="https://example.com/photo.jpg" onClose={() => setOpen(false)} />

// Array of URLs
<ReactBnbGallery
  show={open}
  photos={[
    'https://example.com/photo1.jpg',
    'https://example.com/photo2.jpg',
  ]}
  onClose={() => setOpen(false)}
/>

// Array of photo objects
<ReactBnbGallery
  show={open}
  photos={[
    {
      photo: 'https://example.com/photo1.jpg',
      thumbnail: 'https://example.com/photo1-thumb.jpg',
      caption: 'Mountain sunrise',
    },
  ]}
  onClose={() => setOpen(false)}
/>

phrases

Overrides the built-in UI strings. Useful for internationalization. Pass only the keys you want to override — the rest fall back to defaults.

// Default phrases (for reference):
// {
//   noPhotosProvided: 'No photos to show',
//   showPhotoList: 'Show photo list',
//   hidePhotoList: 'Hide photo list',
// }

<ReactBnbGallery
  show={open}
  photos={photos}
  phrases={{
    noPhotosProvided: 'No hay fotos disponibles',
    showPhotoList: 'Mostrar lista',
    hidePhotoList: 'Ocultar lista',
  }}
  onClose={() => setOpen(false)}
/>

preloadSize

The number of photos to preload when the gallery opens. Increasing this value improves perceived performance when navigating quickly, at the cost of extra network requests.

<ReactBnbGallery
  show={open}
  photos={photos}
  preloadSize={10}
  onClose={() => setOpen(false)}
/>

prevButtonPressed

Callback fired when the previous ← control button is clicked.

<ReactBnbGallery
  show={open}
  photos={photos}
  prevButtonPressed={() => console.log('Prev clicked')}
  onClose={() => setOpen(false)}
/>

rightKeyPressed

Callback fired when the right arrow key is pressed.

<ReactBnbGallery
  show={open}
  photos={photos}
  rightKeyPressed={() => console.log('Right key pressed')}
  onClose={() => setOpen(false)}
/>

show

Controls the visibility of the gallery modal. Set to true to open and false to close. Pair this with onClose to keep state in sync.

const [open, setOpen] = useState(false);

<>
  <button onClick={() => setOpen(true)}>Open gallery</button>
  <ReactBnbGallery
    show={open}
    photos={photos}
    onClose={() => setOpen(false)}
  />
</>

showThumbnails

When true, a strip of thumbnail images is displayed at the bottom of the gallery for quick navigation. Set to false to hide it.

<ReactBnbGallery
  show={open}
  photos={photos}
  showThumbnails={false}
  onClose={() => setOpen(false)}
/>

wrap

When true, navigating past the last photo loops back to the first, and vice versa. When false, navigation stops at the boundaries.

<ReactBnbGallery
  show={open}
  photos={photos}
  wrap
  onClose={() => setOpen(false)}
/>

zIndex

Sets the CSS z-index of the gallery modal. Increase this value if the gallery appears behind other positioned elements in your layout.

<ReactBnbGallery
  show={open}
  photos={photos}
  zIndex={9999}
  onClose={() => setOpen(false)}
/>

Photo props

These props are passed as objects inside the photos array of ReactBnbGallery.

Prop	Type	Default
`photo`	`string`	`undefined`
`number`	`number`	`undefined`
`alt`	`string`	`undefined`
`thumbnailAlt`	`string`	`undefined`
`caption`	`ReactNode`	`undefined`
`subcaption`	`ReactNode`	`undefined`
`thumbnail`	`string`	`undefined`

photo

The URL of the full-resolution image to display in the gallery viewer. This is the only required field in a photo object.

photos={[
  { photo: 'https://example.com/photo.jpg' },
]}

number

An optional number displayed alongside the photo. Useful for showing a custom index or identifier instead of the auto-generated position.

photos={[
  {
    photo: 'https://example.com/photo.jpg',
    number: 1,
  },
]}

caption

The main caption content shown below the photo. Accepts plain text or custom React content.

photos={[
  {
    photo: 'https://example.com/photo.jpg',
    caption: (
      <span>
        Mountain sunrise in the Alps by{' '}
        <a href="https://example.com/jane-doe">Jane Doe</a>
      </span>
    ),
  },
]}

alt

Accessible text for the full-size image. When omitted, the component falls back to caption.

photos={[
  {
    photo: 'https://example.com/photo.jpg',
    alt: 'Mountain sunrise over a snowy ridge',
    caption: 'Mountain sunrise in the Alps',
  },
]}

thumbnailAlt

Accessible text for the thumbnail image. When omitted, it falls back to alt, then caption.

photos={[
  {
    photo: 'https://example.com/photo-large.jpg',
    thumbnail: 'https://example.com/photo-thumb.jpg',
    alt: 'Mountain sunrise over a snowy ridge',
    thumbnailAlt: 'Thumbnail preview of mountain sunrise',
    caption: 'Mountain sunrise in the Alps',
  },
]}

subcaption

A secondary line rendered below the caption. Accepts plain text or React content.

photos={[
  {
    photo: 'https://example.com/photo.jpg',
    caption: 'Mountain sunrise in the Alps',
    subcaption: (
      <span>
        Photo by <strong>Jane Doe</strong> · Zermatt, Switzerland
      </span>
    ),
  },
]}

thumbnail

The URL of a smaller version of the photo used in the thumbnail strip. The recommended size is 58×50 pixels. If omitted, the full photo URL is used as a fallback, which may affect performance for large images.

photos={[
  {
    photo: 'https://example.com/photo-large.jpg',
    thumbnail: 'https://example.com/photo-thumb.jpg',
  },
]}

Edit this page on GitHub