Installation

Get the latest version from NPM:

npm install astro-lightgallery

Requirements

• 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

Basic Example

Here is a simple example using the default adaptive layout:

---
import { LightGallery } from 'astro-lightgallery'
---
<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: "<h4>Custom Caption</h4>" },
    ]
  }}
  options={{
    thumbnail: true,
    autoplay: true,
  }}
/>

API Reference

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:

{
  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
}

Advanced Usage

Custom Layout with Slot

You can use your own HTML structure by providing content in the default slot:

---
import { LightGallery } from 'astro-lightgallery'
---

<LightGallery
  options={{ thumbnail: true }}
  addPlugins={['zoom', 'fullscreen']}
>
  <a href="/large1.jpg" data-sub-html="Custom caption">
    <img src="/thumb1.jpg" alt="Image 1" />
  </a>
  <a href="/large2.jpg">
    <img src="/thumb2.jpg" alt="Image 2" />
  </a>
</LightGallery>

Adaptive Layout Customization

The adaptive layout automatically adjusts to different screen sizes and supports zoom customization:

<LightGallery
  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:

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
}

Styling

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.

Examples

Please check the Astro-lightgallery online documentation for a complete set of examples, including:

• Navigation controls
• Thumbnail galleries
• Custom layouts
• Plugin configurations

Full code examples are provided for each use case.