--- title: Lightbox summary: A lightbox opens images and videos in a fullscreen overlay above the page. Use it for galleries, photo grids, and media previews. docs-libs: [fslightbox] description: Open images and videos in a fullscreen lightbox. --- import Example from '@components/Example.astro'; import { Code } from 'astro:components'; import { site } from '@shared/lib/site.ts'; ## Overview The lightbox shows a full size image or video above the page. The user can move between slides, open the overlay in fullscreen, and close it. Tabler uses the [fslightbox](https://fslightbox.com/) library and styles the overlay to match the theme. The backdrop uses the theme backdrop color and blur, so the lightbox looks the same in light and dark mode. ## Installation The lightbox is not part of the Tabler CSS bundle. You need to add the fslightbox script to your page. Install it with npm: ```shell npm install fslightbox ``` You can also include the script from a CDN. Add it at the end of the `` tag:

`}
/>

The script runs on load. It reads all `` tags with the `data-fslightbox` attribute and handles their clicks. You do not need to write any init code.

## Usage

### Single image

Add `data-fslightbox` to a link and set `href` to the full size image. The link content can be anything, for example a thumbnail.



  



### Gallery

Give the same `data-fslightbox` value to several links. They become one gallery, and the user can move between the slides with the arrows or arrow keys.



  
    
      
    
  
  
    
      
    
  
  
    
      
    
  
  
    
      
    
  



### Separate galleries

Use a different `data-fslightbox` value for each group. Each value creates its own lightbox instance, so slides from one group never mix with another.



  
    
      
    
  
  
    
      
    
  
  
    
      
    
  
  
    
      
    
  



### Text links

The link does not have to be an image. Any link with `data-fslightbox` opens the lightbox.


 Open photo 
 Open second photo 


### Videos and YouTube

A link to a video file or to a YouTube URL opens a player inside the lightbox. The library reads the source type from the URL.


 Play YouTube video 


Use these attributes to control the media:

| Attribute | Description |
| --- | --- |
| `data-type` | Sets the source type when the URL has no file extension. Use `image`, `video`, `youtube`, or `custom`. |
| `data-video-poster` | Sets the poster image of a video slide. |
| `data-autoplay` | Plays the video when its slide opens. |

```html

  Play video

```

### Separate thumbnail and source

Use `data-href` when the link should point somewhere else than the lightbox slide. The lightbox uses `data-href`, and `href` stays the normal link target.

```html

  

```

### Custom sources

Set `href` to the id of an element on the page. The lightbox clones that element and shows it as a slide. Use it for iframes, maps, or any custom markup.

```html
Open Vimeo video

```

### Open from JavaScript

Every gallery is stored in the global `fsLightboxInstances` object under its `data-fslightbox` value. Use `open()` with a slide index to open it, and `close()` to hide it.

```js
// open the second slide of the "gallery" group
fsLightboxInstances['gallery'].open(1)

// close it
fsLightboxInstances['gallery'].close()
```

### Dynamic content

The script reads the links only once. Call `refreshFsLightbox()` after you add or remove links, for example after loading more photos.

```js
document.querySelector('#photos').insertAdjacentHTML('beforeend', newPhotoHtml)
refreshFsLightbox()
```

## Examples

### Photo grid

Mix column sizes to build a photo grid. All links share one `data-fslightbox` value, so the whole grid is a single gallery.



  
    
      
    
  
  
    
      
        
          
        
      
      
        
          
        
      
      
        
          
        
      
      
        
          
        
      
    
  



### Card gallery

Put the gallery inside a card to show it next to other page content.



  Photos
  
    
      
        
          
        
      
      
        
          
        
      
      
        
          
        
      
    
  



## Accessibility

- Keep a real `href` on every link, so the image opens even when JavaScript fails.
- Add `alt` text to thumbnail images. For a background image, add a text label inside the link and hide it with `visually-hidden`.
- The lightbox can be closed with the `Escape` key. Slides change with the left and right arrow keys, and `F11` toggles fullscreen.
- On touch devices the user can swipe left and right to change slides.
- Do not use `data-autoplay` for long videos with sound, because it starts without user action.