Astro component for lightgallery, JavaScript gallery for building beautiful image and video galleries and carousel (including thumbnail) for the web and the mobile
npm install astro-lightgallery
Astro LightGallery is the native Astro component for
lightGallery.
It's a feature-rich, modular JavaScript gallery plugin for
building beautiful image and video galleries for the web and mobile devices.
This component provides an easy-to-use Astro integration with TypeScript support,
responsive layouts, automatic plugin loading, and both layout-based and custom HTML approaches.
bash
npm install astro-lightgallery
`
$3
- Astro 5.x or higher
- TypeScript support (included)
The package automatically includes the required lightGallery CSS and provides TypeScript definitions.
License
Astro-lightGallery is released under the MIT license.
Astro-lightGallery is using lightGallery.
lightGallery is a free and open-source library, however,
if you are using the library for business, commercial sites, projects,
and applications, choose the commercial license to keep your source proprietary, to yourself.
Please refer to the lightGallery license page.
Usage
$3
Here is a simple example using the default adaptive layout:
`jsx
---
import { LightGallery } from 'astro-lightgallery'
---
layout={{
imgs: [
{ src: "/img01.jpg", alt: "Image 1" },
{ src: "/img02.jpg", alt: "Image 2", srcThumb: "/thumb02.jpg" },
{ src: "/img03.jpg", alt: "Image 3", subHtml: "Custom Caption
" },
]
}}
options={{
thumbnail: true,
autoplay: true,
}}
/>
`
$3
#### Component Props
The LightGallery component accepts the following props:
- layout (optional): Configuration for the built-in adaptive layout
- imgs: Array of image objects with src, optional srcThumb, alt, and subHtml
- adaptive.zoom: Zoom factor (default: 100) to scale the gallery
- classContainer: Custom CSS class for the container
- classItem: Custom CSS class for individual items
- options (optional): LightGallery settings object
- Supports all native lightGallery options
- Plugins are automatically loaded based on options (e.g., thumbnail: true loads thumbnail plugin)
- addPlugins (optional): Array of plugin names to load manually
- 'thumbnail', 'autoplay', 'comment', 'fullscreen', 'hash', 'mediumZoom', 'pager', 'relativeCaption', 'rotate', 'share', 'video', 'vimeoThumbnail', 'zoom'
- id (optional): Custom ID for the gallery (auto-generated if not provided)
- class (optional): CSS class for the gallery container
#### Image Object Properties
Each image in the layout.imgs array can have:
`typescript
{
src: string, // Required: URL of the full-size image
srcThumb?: string, // Optional: URL of thumbnail (defaults to src)
alt?: string, // Optional: Alt text for accessibility
subHtml?: string, // Optional: HTML caption for the image
loading?: 'lazy' | 'eager' // Optional: Native image loading strategy
}
`
$3
#### Custom Layout with Slot
You can use your own HTML structure by providing content in the default slot:
`jsx
---
import { LightGallery } from 'astro-lightgallery'
---
options={{ thumbnail: true }}
addPlugins={['zoom', 'fullscreen']}
>
`
#### Adaptive Layout Customization
The adaptive layout automatically adjusts to different screen sizes and supports zoom customization:
`jsx
layout={{
imgs: [...],
adaptive: { zoom: 150 }, // 150% zoom
classContainer: "my-gallery-container",
classItem: "my-gallery-item hover:opacity-80"
}}
/>
`
#### Programmatic Access
You can access the lightGallery instance programmatically:
`javascript
import { getLightGalleryFromUniqueSelector } from 'astro-lightgallery';
// Get the lightGallery instance
const lgInstance = await getLightGalleryFromUniqueSelector('#my-gallery-id');
if (lgInstance) {
lgInstance.openGallery(0); // Open at first image
}
`
$3
The component includes responsive CSS that adapts to different screen sizes:
- Desktop: Flexible height based on viewport (20vh by default)
- Portrait mode: Adjusted height (15vh)
- Small screens: Full-width layout with constrained height
- Short screens: Increased height (40vh) for better visibility
Custom styling can be applied through the class, classContainer, and classItem` props.