Image Gallery
Interactive image gallery with lightbox modal, keyboard navigation, and responsive grid layout
Basic Usage
A simple image gallery with default settings:
<neura::image-gallery :images="[
[
'photo' => 'https://example.com/image1.jpg',
'alt' => 'Image description'
],
[
'photo' => 'https://example.com/image2.jpg',
'alt' => 'Image description 2'
],
]" />Image Format Options
The component accepts images with different property names:
<neura::image-gallery :images="[
['photo' => 'url', 'alt' => 'description'],
['url' => 'url', 'alt' => 'description'],
['src' => 'url', 'caption' => 'description'],
]" />Grid Columns
Control the number of columns in the grid:
2 Columns
<neura::image-gallery :images="$images" :columns="2" />3 Columns
4 Columns
Lightbox Features
Click any image to open it in a full-screen lightbox modal with navigation controls:
Features:
- Click any image to open in lightbox
- Navigate with arrow buttons or keyboard (← →)
- Close with Escape key or click outside
- Smooth transitions and animations
- Responsive design
Custom Gap
Adjust the spacing between images:
<neura::image-gallery
:images="$images"
:columns="3"
gap="gap-2"
/>Disable Keyboard Navigation
Disable keyboard navigation if needed:
<neura::image-gallery
:images="$images"
:keyboardNavigation="false"
/>Complete Example
A complete gallery with all features:
Properties
| Property | Type | Default | Description |
|---|---|---|---|
| images | array | [] | Array of image objects with photo/url/src and alt/caption properties |
| columns | integer | 5 | Number of columns in the grid (2-6). For 5 columns, uses responsive: 2 on mobile, 5 on desktop |
| gap | string | gap-5 | Tailwind gap class for spacing between images (e.g., gap-2, gap-4, gap-5) |
| aspectRatio | string | aspect-[5/6] lg:aspect-[2/3] xl:aspect-[3/4] | Tailwind aspect ratio classes for image containers |
| keyboardNavigation | boolean | true | Enable or disable keyboard navigation (arrow keys) in lightbox |
Image Object Structure
Each image in the images array can have the following properties:
| Property | Type | Required | Description |
|---|---|---|---|
| photo | string | No* | Image URL (one of photo, url, or src is required) |
| url | string | No* | Image URL (alternative to photo) |
| src | string | No* | Image URL (alternative to photo) |
| alt | string | No | Alt text for the image (used for accessibility) |
| caption | string | No | Caption text (alternative to alt) |
Keyboard Shortcuts
←
Previous image
→
Next image
Esc
Close lightbox
Best Practices
Provide alt text for accessibility
Always include descriptive alt text for each image to improve accessibility and SEO
Optimize images before use
Use optimized images with appropriate file sizes to ensure fast loading times
Choose appropriate column count
Select the number of columns based on your content and screen size requirements
Use consistent image aspect ratios
Maintain consistent aspect ratios across images for a cleaner, more professional appearance
Test on mobile devices
Ensure the gallery works well on mobile devices with touch interactions