BNA

BNA UI
26

Gallery

PreviousNext

A responsive image gallery component with fullscreen viewing, zoom, and gesture support.

Installation

pnpm dlx bna-ui add gallery

Usage

import { Gallery } from '@/components/ui/gallery';
const galleryItems = [
  {
    id: '1',
    uri: 'https://picsum.photos/400/400?random=1',
    title: 'Beautiful Landscape',
    description: 'A stunning view of mountains and valleys',
  },
  {
    id: '2',
    uri: 'https://picsum.photos/400/400?random=2',
    title: 'City Skyline',
    description: 'Urban architecture at its finest',
  },
  // ... more items
];
 
<Gallery items={galleryItems} />;

Examples

Default

Custom Grid

With Titles and Descriptions

Different Layouts

With Controls

With Overlays

API Reference

Gallery

The main gallery component that displays images in a grid layout with fullscreen viewing capabilities.

PropTypeDefaultDescription
itemsGalleryItem[]-Array of gallery items to display.
columnsnumber4Number of columns in the grid layout.
spacingnumber0Spacing between grid items in pixels.
borderRadiusnumber0Border radius for gallery items.
aspectRationumber1Aspect ratio for gallery items (width/height).
showPagesbooleanfalseShow page indicator in fullscreen mode.
showTitlesbooleanfalseShow image titles in grid view.
showDescriptionsbooleanfalseShow image descriptions in grid view.
enableFullscreenbooleantrueEnable fullscreen viewing mode.
enableZoombooleantrueEnable zoom functionality in fullscreen mode.
enableDownloadbooleanfalseShow download button in fullscreen mode.
enableSharebooleanfalseShow share button in fullscreen mode.
onItemPress(item: GalleryItem, index: number) => void-Custom handler for item press events.
onDownload(item: GalleryItem) => void-Handler for download button press.
onShare(item: GalleryItem) => void-Handler for share button press.
renderCustomOverlay(item: GalleryItem, index: number) => React.ReactNode-Custom overlay renderer for grid items.

GalleryItem

Interface for gallery items.

PropertyTypeRequiredDescription
idstringYesUnique identifier for the gallery item.
uristringYesImage URI for the full-size image.
titlestringNoOptional title for the image.
descriptionstringNoOptional description for the image.
thumbnailstringNoOptional thumbnail URI (falls back to uri).

Features

Gesture Support

  • Pinch to zoom: Zoom in and out on images in fullscreen mode
  • Double tap to zoom: Quick zoom to 2.5x scale or reset to original size
  • Pan when zoomed: Drag zoomed images to view different areas
  • Swipe navigation: Horizontal swipe to navigate between images

Fullscreen Mode

  • Immersive fullscreen viewing experience
  • Thumbnail navigation bar at the bottom
  • Top controls for sharing, downloading, and closing
  • Page indicators showing current position

Responsive Design

  • Automatically adjusts to screen size
  • Configurable grid columns and spacing
  • Maintains aspect ratios across different devices
  • Smooth animations and transitions

Performance Optimizations

  • Lazy loading of off-screen images
  • Efficient gesture handling with React Native Reanimated
  • Optimized FlatList rendering for large galleries
  • Thumbnail support for faster grid loading

Accessibility

The Gallery component includes accessibility features:

  • Proper keyboard navigation support
  • Screen reader compatibility
  • High contrast support for UI elements
  • Semantic structure for assistive technologies
  • Touch target sizes meet accessibility guidelines

Troubleshooting

Common Issues

Gestures not working:

  • Ensure react-native-gesture-handler is properly installed and configured
  • Make sure the component is wrapped in GestureHandlerRootView

Images not loading:

  • Verify image URIs are accessible
  • Check network connectivity
  • Ensure proper CORS configuration for web images

Performance issues with large galleries:

  • Consider implementing pagination
  • Use thumbnail images for grid view
  • Optimize image sizes and formats

Zoom not working properly:

  • Verify react-native-reanimated is correctly set up
  • Check that enableZoom prop is set to true
  • Ensure proper gesture handler configuration
File PickerHello Wave