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.

DEMO

Get the latest version from NPM:

npm install astro-lightgallery

• Astro 5.x or higher
• TypeScript support (included)

The package automatically includes the required lightGallery CSS and provides TypeScript definitions.

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.

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,
  }}
/>

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

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
}

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>

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"
  }}
/>

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
}

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.

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.