LightGallery Formatter turns a Drupal media field into a clean gallery that works well on touch screens. It uses the lightGallery JavaScript library. You set up a gallery style once and then reuse it on any field.

It is built and maintained by Andrii and Denys.

A gallery on a Drupal page. Click any picture to open the lightbox.

What it is

LightGallery Formatter is a field formatter for Media reference fields. Pick it in Manage display, choose a profile, and your images, remote videos (YouTube and Vimeo) and PDF files open in a lightbox.

You do not write JSON or code. All settings are checkboxes and dropdown lists in the admin screens.

The formatter shows up for a Media reference field when that field can hold an image Media type, or the standard Document Media type (a file based type with the machine name document). It also shows up when the field has no limit on Media types. A field that only allows remote video will not offer it.

Why it exists

The existing drupal/lightgallery module asks you to set up each field on its own. That gets slow when a site has many galleries.

This module uses reusable profiles instead. Create as many as you need. Change one profile and every gallery that uses it follows. You set it up once and use it everywhere.

You also do not need to set up the library by hand. lightGallery 2.9.0 comes with the module, together with React. There are no extra downloads and no custom Composer paths.

Key features

• Reusable profiles. One profile can drive many fields.
• Mixed media in one gallery. Images, YouTube videos, Vimeo videos and PDF files, in the order the editor chose.
• Bundled library. lightGallery and React are included. No manual JavaScript downloads and no Composer library steps.
• 31 transitions. Slide, Fade, Zoom, Lollipop, Rotate, Tube and more, all in one dropdown list.
• Rich controls. Zoom, fullscreen, thumbnails, a download button and keyboard navigation with the Esc and arrow keys. The mouse wheel is optional.
• Touch support. Swipe and drag on phones and tablets. You can turn either one off.
• Auto hide controls. Optional, with a delay you choose.
• Video thumbnails. YouTube and Vimeo thumbnails come from the thumbnail of the Media item.
• Profile cloning. Copy a profile and use it as the start of a new one. New in 1.1.0.
• PDF slides. PDF files open in the lightbox with the viewer that is built into the browser. New in 1.1.0.
• Config export. Profiles move between sites with standard Drupal configuration.
• Live preview. Test a profile while you edit it. This needs an optional submodule.
• Fallback links. Image and PDF links still work before the script loads, or if it fails to load.
• Status report entry. The Drupal status report shows the version of the bundled lightGallery.

The lightbox with its toolbar and the thumbnail strip.

Requirements

• Drupal ^10.3, ^11 or ^12
• The core Media and Media Library modules. The module needs both.
• For PDF files, the standard Document Media type and at least one image based Media type for the PDF thumbnail

Installation

Install the module with Composer. You do not need Node.js or npm on your site. The JavaScript is already built and comes inside the module.

composer require drupal/lightgallery_formatter

Enable it with Drush.

drush en lightgallery_formatter

You can also enable the optional submodules.

drush en lightgallery_formatter_preview lightgallery_formatter_demo

If you prefer the admin screens, go to Extend, find the LightGallery group and tick the modules you want.

Quick start

Step 1. Create a profile

1. Go to Configuration → Media → LightGallery (/admin/config/media/lightgallery).
2. Click Add LightGallery profile.
3. Enter a Label and a Machine name. You can only change the machine name while the profile is new.
4. Set the general options. See "Profiles and settings" below.
5. Turn on the plugins you want, such as thumbnails, zoom or fullscreen.
6. If the Preview submodule is on, click Generate Preview at the top of the form to test your settings.
7. Save the profile.

The module comes with one profile called Default. You need the permission Administer LightGallery formatter to manage profiles.

You find LightGallery under Configuration and then Media.The list of profiles. Use the arrow next to Edit to see more actions.The profile form with the preview on top.

Step 2. Use the profile on a media field

1. Go to Structure → Content types → (your type) → Manage display.
2. Find your Media reference field.
3. Set the formatter to LightGallery.
4. Click the gear icon.
5. Choose your LightGallery Profile. Only enabled profiles are listed.
6. Choose an image style for Gallery thumbnails (inline on page).
7. If the field holds PDF files, pick a PDF thumbnail. See "Working with PDFs" below.
8. Save.

Also check that the field allows the Media types you plan to use. Tick Image for pictures, Remote video for YouTube and Vimeo, and Document for PDF files.

Set the formatter of your media field to LightGallery.Choose which Media types the field can hold.

Step 3. Check the result

Open a piece of content with images, videos or PDF files. They show as one gallery, in the same order the editor chose.

A photo open in the lightbox.

Profiles and settings

A profile is a Drupal configuration entity (lightgallery_profile). It holds a label, a machine name, an Enabled checkbox and the settings of every plugin. Only enabled profiles can be picked in the formatter settings of a field.

Cloning a profile (new in 1.1.0)

Cloning is a quick way to make a variation of a profile you already like.

1. Go to Configuration → Media → LightGallery (/admin/config/media/lightgallery).
2. In the Operations column of the profile you want to copy, open the dropdown and choose Clone.
3. The clone form opens at /admin/config/media/lightgallery/{machine_name}/clone. It is the same form as Add and Edit, already filled in with the settings of the source profile.
4. The Label is the label of the source profile followed by (copy). Change it.
5. The Machine name is empty. Type a new one with lowercase letters, numbers and underscores. A name that is already taken is rejected.
6. Change any settings you like, then click Save.

Good to know

• Nothing is saved until you click Save. If you leave the page, no clone is created.
• The Enabled checkbox and the settings of all plugins are copied. That includes General, Thumbnail, Zoom, Video and the others, with their on or off state.
• The source profile is never changed.
• The clone is a new and separate profile. Editing it later does not touch the original, and the other way round.
• After saving you land on the profile list with the message "Created the ... LightGallery profile."
• Cloning needs the same permission as editing, which is Administer LightGallery formatter.

General settings

These settings are always on. You find them in the General Settings section of the form.

• License key. See "A note on the license key" below.
• Enable looping. Go from the last slide back to the first one.
• Preload count. How many slides to load ahead, from 1 to 5.
• Transition speed (ms). The speed of the animation in milliseconds.
• Transition mode. The style of the transition. There are 31 to choose from.
• Closable, Close on tap and Close with Esc key. These control how visitors can close the lightbox.
• Keyboard navigation. Arrow keys and similar keys.
• Show close icon and Show maximize icon.
• Hide controls delay (ms). Hides the toolbar after this delay. Use 0 to keep it visible.
• Show counter. Shows the slide number and the total.
• Enable download. Shows the download button.
• Enable desktop drag and Enable touch swipe.
• Mouse wheel navigation.
• Allow media overlap. Keep this on if you want to see the thumbnail toggle and other plugin icons in the toolbar.

The Default profile that comes with the module has the download button off. A brand new profile starts with it on.

Plugins

The code has 12 plugins. General is always on. You switch on the other 11 one by one inside a profile. The README counts 11 because it leaves out the Video plugin.

• General. The core options described above. Always on.
• Video. Lets video slides play in the lightbox, for YouTube and Vimeo. Settings include autoplay for the first video, autoplay when the slide changes, going to the next slide when a video ends, and the Video.js option.
• Thumbnail Navigation. A strip of thumbnails at the bottom of the lightbox. Settings include the image style, width, height, margin, the position of the current thumbnail, alignment, a toggle button and where to place it.
• Zoom. Zoom in and out, and show the actual size. Settings include scale, infinite zoom, the actual size button, the zoom icons and a delay before zoom is enabled.
• Fullscreen. Fills the whole browser window. It has no settings.
• Pager. A page number indicator.
• Relative Caption. Captions placed next to the image.
• Rotate. Rotate and flip images. Settings include rotate speed, rotate left and right, and flip horizontal and vertical.
• Autoplay. An automatic slideshow. Settings include auto start, the interval (5000 ms by default), a progress bar, forced autoplay, and the controls with their position.
• Medium Zoom. A zoom in the style of Medium. Settings include margin and background color.
• Share. Social share buttons for Facebook, Twitter and Pinterest. You can turn each one on or off and change the text of each button.
• Hash. Deep links to a single slide in the page address. Settings include enable hash and custom slide names.

Every plugin except General has its own Enable ... plugin checkbox. On a new profile only the checked plugins are sent to the browser.

Two kinds of thumbnails

• Gallery thumbnails are the grid on the page. You choose the image style in the field formatter.
• Lightbox thumbnails are the strip inside the lightbox. You choose the image style in the profile, under Thumbnail Navigation. If you leave it empty, the strip uses the gallery thumbnail style of the field.

Deep links (Hash plugin)

With the Hash plugin on, the page address changes as you move through the gallery. The format is #lg={gallery-id}&slide={index}. The slide index starts at 0. With Custom slide name on, a slide name is used instead of the number when one exists.

If you put more than one gallery with Hash turned on on the same page, test the deep links before you rely on them.

Known plugin interactions

• Hash together with Thumbnail Navigation may act oddly in some browsers.
• Relative Caption may write a warning to the browser console during transitions. It does not change how the gallery works.
• Clicks of Medium Zoom may clash with clicks on the thumbnail strip.

If you see a problem, turn one of the plugins off in the profile.

A note on the license key

The bundled lightGallery 2.9.0 is open source under the GPLv3 license. The package file of the library and the license header in the bundled file both say GPLv3.

The profile form has a License key field. It is filled in with 0000-0000-000-0000, and the help text says to use this value for non commercial use. The module does not check the key. It passes the value to lightGallery, and the library only writes a message to the browser console. If the key is the default one, the library logs a warning that it is not valid for production use. If the field is empty, it logs an error that asks for a valid key. The gallery works either way.

The commercial license is for projects that keep their source code closed. The lightGallery license page says that GPLv3 is free and that the paid license is for closed source projects. Drupal modules are GPL, so for most Drupal sites the GPLv3 route applies. If you are not sure about your own project, read the terms at https://www.lightgalleryjs.com/license/ or ask the authors of the library.

Supported media types

• Images. Core Media image items. Use Drupal image styles for the thumbnails. In the formatter settings, under Gallery item source by media type, you can pick which image field to use for each Media type.
• YouTube and Vimeo. Remote video items, with thumbnails taken from the thumbnail of the Media item. The formatter treats Media types with the machine names remote_video, video or oembed_video as remote video. Turn on the Video plugin in the profile so the videos play in the lightbox.
• PDF files. The standard Document Media type, with the machine name document and a file source. New in 1.1.0.
• HTML5 video files. The field formatter does not support them. See "Video notes" below.

Working with PDFs

How a PDF shows up

• The PDF opens inside the lightbox as an iframe slide, which uses the PDF viewer of the browser. The module does not include its own PDF viewer. There is no pdf.js and no embed or object tag in the code.
• Images and PDF files can sit in the same field. The order set by the editor is kept for the previous and next buttons.
• Each PDF slide has a caption with the file name and an Open or download PDF link that opens the original file in a new tab.

What counts as a PDF

• The Media item must be of the document type with a file source.
• The MIME type of the stored file must be exactly application/pdf. A file name that ends in .pdf is not enough.
• The code sets no limit on file size or on the number of PDF files in a gallery.

The PDF thumbnail

• A PDF has no picture of its own, so you pick one image for it. This is a setting of the field display and not of the profile.
• In the formatter settings (the gear icon), open Gallery item source by media type and look for PDF settings. On fields with no limit on Media types, PDF settings is shown on its own.
• Click Select PDF thumbnail. This opens the normal Drupal Media Library in a popup. You can choose exactly one item. Only image based Media types are offered.
• After you choose, the summary says "Selected thumbnail", and the button changes to Change PDF thumbnail.
• The chosen image must be published and visible to the user. It is shared by all PDF files in that field display. It is used for the grid on the page and for the strip in the lightbox, each with its own image style.
• If no thumbnail is picked, or the picked one is unpublished, hidden or deleted, the PDF files in that gallery are left out. The images still show.
• If the site has no image based Media type, the selector is not shown and the setting is saved as 0.
• The summary line under the formatter shows "PDF thumbnail: not configured" until you choose one.

When something cannot be shown

• A Media item that cannot be shown is skipped, and the gallery keeps working. One short warning goes to the lightgallery_formatter log channel. The possible reasons are a missing source field, a missing file, a wrong MIME type, an unsupported Media type or a missing PDF thumbnail.
• If every item is skipped, nothing is shown for that field.

When the browser cannot show PDF files inline

• The script checks whether the PDF viewer of the browser is turned on. If it is not, PDF files do not open in the lightbox. The thumbnail becomes a normal link to the PDF, with an Open or download PDF link under it.
• A short notice appears above the gallery. It says "Your browser cannot display PDFs here. You can still open or download each PDF." It also adds a hint for Chrome, Edge, Firefox or Safari on how to turn the viewer on.
• Without JavaScript, or if the gallery fails to load, the page still shows each PDF as a thumbnail with the file name and an Open PDF in a new tab link.

Video notes

• YouTube and Vimeo work through Media items of the remote video type. The playable address is read from the source field of the Media item.
• The Video plugin form mentions HTML5 videos and Video.js, and the bundled library can play HTML5 video. But the field formatter has no code that builds a slide from an uploaded video file. A Media item from a file based video type would show as an image slide that uses its thumbnail. So we do not list HTML5 video as supported.
• The option to go to the next slide when a video ends does not work with YouTube. The plugin form says so too.

Under the hood

• The gallery is built with React and the lightGallery React component. Vite bundles them into one file, js/dist/lightgallery-react.js.
• The server first prints plain links and thumbnails. When the script loads, the interactive gallery replaces them. If the script fails, the plain links come back.
• The bundled versions are lightGallery 2.9.0 and React 18.
• No jQuery is used.

Submodules

Both submodules are optional.

LightGallery Formatter Preview

Adds a Generate Preview button to the profile form, so you can see the gallery with your current settings before you save. It also holds the sample image, PDF and remote video Media used by the preview and the demo, including a sample PDF thumbnail.

drush en lightgallery_formatter_preview -y

LightGallery Formatter Demo

Creates demo content for testing galleries with mixed images, PDF files and videos. It is built for the demo_umami installation profile and reuses the sample Media from the Preview module. On install it also picks the PDF thumbnail of the Preview module for the demo display. We recommend it if you want to see what the module can do.

drush en lightgallery_formatter_demo -y

Config export and deploy

Each profile is Drupal configuration, saved as lightgallery_formatter.profile.{machine_name}. It contains the machine name, the label, the enabled flag and the plugin settings. Export and import it the same way you do for the rest of your site. Build a profile on your development site, export it, then deploy.

The formatter settings of a field, including the chosen profile and the PDF thumbnail, live in the display configuration of that field (core.entity_view_display...). The PDF thumbnail is stored as a Media ID, so check that this Media item exists on the target site.

drush config:export drush config:import

Compatibility and releases

• 1.1.0. Released on October 1, 2026 (the git tag is dated September 28). Works with Drupal ^10.3 || ^11 || ^12.
• 1.0.9. Released on March 20, 2026. Works with Drupal ^10.3 || ^11.

What is new in 1.1.0

• PDF support, in the same gallery as images and remote videos
• A shared PDF thumbnail, chosen for each field display through the Media Library
• PDF files open in the viewer of the browser, with a clear fallback and a notice when the viewer is off
• Profile cloning from the profile list (Operations → Clone)
• Drupal 12 compatibility
• The core Media Library is now a required dependency
• The fallback markup now stays on the page until the gallery has loaded, and comes back if loading fails
• Safer output, because file names, labels and attributes are escaped
• The Drupal status report shows the version of the bundled lightGallery
• Many new automated tests

The project page says 56 sites report using the module. Stable releases are covered by the Drupal security advisory policy.

For developers

The module uses ddev-drupal-contrib for local development.

git clone git@git.drupal.org:project/lightgallery_formatter.git cd lightgallery_formatter ddev start ddev lgf:init

The command ddev lgf:init installs Drupal with the demo_umami profile, turns on the module with demo content and gives you an admin login. Other commands are ddev phpcs, ddev phpcbf, ddev phpstan and ddev phpunit.

You only need Node.js if you want to change the front end. The source is in js/react/ and the styles are in css/ (Sass). Build with npm run build, which uses Vite for the JavaScript and Sass for the CSS. The Node version is set in .nvmrc. The built files go in js/dist/.

Links

• Project page https://www.drupal.org/project/lightgallery_formatter
• Issue queue https://www.drupal.org/project/issues/lightgallery_formatter
• Source code https://git.drupalcode.org/project/lightgallery_formatter
• Tutorial video on YouTube https://www.youtube.com/watch?v=FyHGh2xYSEo
• lightGallery library https://www.lightgalleryjs.com/
• lightGallery license https://www.lightgalleryjs.com/license/

Credits

• Built and maintained by Andrii and Denys.
• The lightGallery library is by Sachin Neravath. The bundled version, 2.9.0, is under the GPLv3 license. React is bundled too, under the MIT license.
• Thanks to @bbu23 and @nk_ for their input on the profile based settings.
• The screenshots come from the project page and the tutorial video on Drupal.org and YouTube.