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


## Installation Get the latest version from NPM: ```bash 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](https://github.com/sachinchoolur/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](https://www.lightgalleryjs.com/license/). ## Usage ### Basic Example Here is a simple example using the default adaptive layout: ```jsx --- import { LightGallery } from 'astro-lightgallery' --- Custom Caption" }, ] }} 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 - `type`: Accepted values are `adaptive` (default) or `google-photos` (preferred one as responsive) - `imgs`: Array of image objects with `src`, optional `srcThumb`, `alt`, and `subHtml` - `adaptive.zoom`: Zoom factor (default: 100) to scale the gallery - `googlePhotos`: google photos layout parameters (cf. [Google Photos Layout Customization](https://github.com/pascal-brand38/astro-lightGallery#google-photo-layout-customization)) - `classContainer`: Custom CSS class for the container - `classItem`: Custom CSS class for individual items - **`options`** (optional): [LightGallery settings](https://www.lightgalleryjs.com/docs/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 position?: string; // position of the point of interest of the image, to be used with `object-position` } ``` Images are displayed using `img` html keyword be default. In such a case, `img.src` must be a public path, or a url path. In order to use the optimized astro asset [](https://docs.astro.build/fr/guides/images/#image-), `layout.srcs` must be provided as a [meta.glob](https://docs.astro.build/fr/guides/imports/#importmetaglob) path in `/src`, such as `import.meta.glob<{ default: ImageMetadata }>('/src/images/*.{jpg,webp}')`, and images stored in this path to be found during the build. Check [this example](https://github.com/pascal-brand38/astro-dev/blob/main/src/content/docs/packages/astro-lightgallery/GooglePhotosLayout.astro) `position` is used hrough the css rule [object-position](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/object-position) of the image. The first value is the vertical position, and the second value is the horizontal position. Example values are `left top`, `right bottom`, `20% 50%` for the center of the image with a focus on the upper part, and `250px 125px`. Default value is `50% 50%` for the center of the image. Check [this example](https://github.com/pascal-brand38/astro-dev/blob/main/src/content/docs/packages/astro-lightgallery/GooglePhotosLayout.astro) ### Advanced Usage #### Custom Layout with Slot You can use your own HTML structure by providing content in the default slot: ```jsx --- import { LightGallery } from 'astro-lightgallery' --- Image 1 Image 2 ``` #### Adaptive Layout Customization The adaptive layout automatically adjusts to different screen sizes and supports zoom customization: ```jsx ``` #### Google Photo Layout Customization Google photos layout reflect the layout used on Google Photos. The main pro over the `adaptive` layout is that it is responsive. To use it, jus use the following: ```jsx ``` which is the same as ```jsx ``` This means that: * default height and max-height of a picture is `45vw` (45% of the viewport width) * on screen larger than 601px, height and max-height will be respectivelly 20vw and 205px As many breakpoints as needed can be added. #### 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 } ``` ### 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](https://pascal-brand38.github.io/astro-dev/packages/astro-lightgallery) for a complete set of examples, including: - Navigation controls - Thumbnail galleries - Custom layouts - Plugin configurations Full code examples are provided for each use case.