Gallery - API Reference

Quick Start

Get a filterable image gallery with lightbox running in under 2 minutes.

1. Include the CSS and JavaScript

<!-- CSS -->
<link rel="stylesheet" href="styles/gallery.css">

<!-- JavaScript (at end of body) -->
<script src="javascript/gallery.js"></script>

2. Add the HTML Structure

<div class="rsl-gallery" data-lightbox="my-lightbox" role="list">
    <article class="rsl-gallery-item" role="listitem">
        <a href="large-image.jpg" class="rsl-gallery-link">
            <div class="rsl-gallery-image">
                <img src="thumbnail.jpg" alt="Description" loading="lazy">
            </div>
            <div class="rsl-gallery-overlay">
                <div class="rsl-gallery-info">
                    <h3 class="rsl-gallery-title">Image Title</h3>
                    <p class="rsl-gallery-meta">Category</p>
                </div>
            </div>
        </a>
    </article>
    <!-- More items... -->
</div>

<!-- Lightbox Modal -->
<div class="rsl-lightbox" id="my-lightbox" role="dialog" hidden>
    <button class="rsl-lightbox-close" aria-label="Close">×</button>
    <button class="rsl-lightbox-prev" aria-label="Previous">‹</button>
    <button class="rsl-lightbox-next" aria-label="Next">›</button>
    <div class="rsl-lightbox-content">
        <img src="" alt="" class="rsl-lightbox-image">
        <div class="rsl-lightbox-caption">
            <h3 class="rsl-lightbox-title"></h3>
            <p class="rsl-lightbox-meta"></p>
        </div>
    </div>
    <div class="rsl-lightbox-counter">
        <span class="rsl-lightbox-current">1</span> / <span class="rsl-lightbox-total">1</span>
    </div>
</div>

Masonry-style responsive grid layout
Built-in lightbox with keyboard navigation
Optional category filtering with animation
Full accessibility support (WCAG 2.1 AA)
Dark mode compatible
Reduced motion support

View Examples Playground

CSS Classes Reference

Gallery Container

Class	Description
`.rsl-gallery`	Main gallery container. Creates a CSS Grid with auto-fill columns.
`.rsl-gallery-filter`	Container for filter buttons. Flexbox with centered content.
`.rsl-gallery-filter-btn`	Filter button styling. Add `.active` for active state.
`.rsl-gallery-status`	Visually hidden live region for screen reader announcements.

Gallery Items

Class	Description
`.rsl-gallery-item`	Individual gallery item container. Default 4:3 aspect ratio.
`.rsl-gallery-item-tall`	Tall variant. Spans 2 rows with 3:4 aspect ratio.
`.rsl-gallery-item-wide`	Wide variant. Spans 2 columns with 2:1 aspect ratio.
`.rsl-gallery-item-large`	Large variant. Spans 2 columns and 2 rows with 1:1 aspect ratio.
`.rsl-gallery-link`	Clickable link wrapper. Opens lightbox on click.
`.rsl-gallery-image`	Image container with object-fit: cover.
`.rsl-gallery-overlay`	Hover overlay with gradient background.
`.rsl-gallery-info`	Container for title and meta text in overlay.
`.rsl-gallery-title`	Image title in overlay.
`.rsl-gallery-meta`	Subtitle/category text in overlay.
`.rsl-gallery-icon`	Expand icon in top-right of overlay.

Lightbox

Class	Description
`.rsl-lightbox`	Fixed position lightbox container. Use `hidden` attribute to hide.
`.rsl-lightbox-close`	Close button positioned top-right.
`.rsl-lightbox-prev`	Previous image button.
`.rsl-lightbox-next`	Next image button.
`.rsl-lightbox-content`	Container for image and caption.
`.rsl-lightbox-image`	The displayed image (max 90vw/80vh).
`.rsl-lightbox-caption`	Container for lightbox title and meta.
`.rsl-lightbox-counter`	Image counter (e.g., "3 / 8").

Data Attributes

Attribute	Element	Description
`data-lightbox`	`.rsl-gallery`	ID of the lightbox element to use for this gallery.
`data-filter`	`.rsl-gallery`	ID of the filter button container to connect to this gallery.
`data-cols`	`.rsl-gallery`	Fixed number of columns (2, 3, or 4). Overrides auto-fill.
`data-category`	`.rsl-gallery-item`	Category name for filtering. Must match `data-filter` button value.
`data-filter`	`.rsl-gallery-filter-btn`	Filter value. Use "all" to show all items.

FilterBus Integration

Gallery items can subscribe to RSL's FilterBus for cross-component filtering based on external filter controls. This enables dashboard scenarios where filter buttons control which gallery items are displayed.

How It Works

Add data-filter-subscribe="key" to gallery items to listen to a FilterBus channel
Add data-filter-value="value" to specify which filter value each item matches
Items without data-filter-value always show
"All" filter value shows all items (case-insensitive)

Visibility Filtering

Add these attributes to .rsl-gallery-item elements:

Attribute	Element	Description
`data-filter-subscribe`	`.rsl-gallery-item`	FilterBus key to subscribe to (e.g., "region", "category").
`data-filter-value`	`.rsl-gallery-item`	Value(s) this item matches. Comma-separated for multiple values (e.g., "north,south"). Item shows when filter matches any value or is "all".

<!-- Gallery items with FilterBus subscription -->
<div class="rsl-gallery" role="list">
    <article class="rsl-gallery-item"
             data-filter-subscribe="region"
             data-filter-value="north"
             role="listitem">
        <!-- North region image -->
    </article>
    <article class="rsl-gallery-item"
             data-filter-subscribe="region"
             data-filter-value="south"
             role="listitem">
        <!-- South region image -->
    </article>
    <article class="rsl-gallery-item"
             data-filter-subscribe="region"
             data-filter-value="all"
             role="listitem">
        <!-- Shows for all regions -->
    </article>
</div>

<!-- FilterBus publishes state changes -->
<script>
// When region filter changes, gallery items auto-update
RSL.FilterBus.publish('region', 'north'); // Shows only north items
RSL.FilterBus.publish('region', 'all');   // Shows all items
</script>

Date Range Filtering

Gallery items can be filtered by date range when connected to a Date Picker via FilterBus. Add data-filterbus-date-field to the gallery container and data-date to each item:

Attribute	Applied To	Description
`data-filterbus-date-field`	Gallery Container	Specifies the data attribute on items containing dates (e.g., "date" looks for `data-date`).
`data-date`	Gallery Item	The date value for this item. Supports ISO (YYYY-MM-DD), US (MM/DD/YYYY), and European (DD.MM.YYYY) formats.

<!-- Date Picker publishes to FilterBus -->
<input type="text"
       data-rsl-date-picker
       data-mode="range"
       data-filterbus-publish="dateFilter">

<!-- Gallery with date filtering enabled -->
<div class="rsl-gallery" data-filterbus-date-field="date">
    <article class="rsl-gallery-item" data-date="2025-12-01">
        <!-- Photo from Dec 1 -->
    </article>
    <article class="rsl-gallery-item" data-date="2025-12-15">
        <!-- Photo from Dec 15 -->
    </article>
    <article class="rsl-gallery-item" data-date="2025-12-28">
        <!-- Photo from Dec 28 -->
    </article>
</div>

JavaScript API

The gallery auto-initializes on DOMContentLoaded. For dynamic content, use the public API:

Method	Description
`RSL.Gallery.init()`	Initialize all `.rsl-gallery` elements on the page. Skips already initialized galleries.
`RSL.Gallery.create(element)`	Initialize a specific gallery element. Sets up filtering and lightbox based on data attributes.
`RSL.Gallery.destroy(element)`	Remove a gallery from the tracking set. Does not remove event listeners.

// Initialize a dynamically added gallery
const newGallery = document.querySelector('#my-new-gallery');
RSL.Gallery.create(newGallery);

// Re-initialize all galleries
RSL.Gallery.init();

Accessibility

WCAG 2.1 AA Compliant

The Gallery component includes comprehensive accessibility features for keyboard and screen reader users.

Keyboard Navigation

Key	Context	Action
`Tab`	Gallery	Move focus between gallery items and controls
`Enter` / `Space`	Gallery item	Open image in lightbox
`Arrow Left/Right`	Filter buttons	Navigate between filter options
`Arrow Left`	Lightbox	Previous image
`Arrow Right`	Lightbox	Next image
`Escape`	Lightbox	Close lightbox

ARIA Attributes

role="list" and role="listitem" for gallery structure
role="tablist" and role="tab" for filter buttons
aria-selected indicates active filter
role="dialog" and aria-modal="true" for lightbox
aria-live="polite" for filter change announcements
Descriptive aria-label on all interactive elements

Focus Management

Focus trap in lightbox keeps keyboard focus contained
Focus returns to triggering element when lightbox closes
Visible focus indicators on all interactive elements
Roving tabindex on filter buttons

CSS Custom Properties

Variable	Default	Description
`--rsl-gallery-gap`	`1rem`	Gap between gallery items
`--rsl-gallery-radius`	`8px`	Border radius of gallery items
`--rsl-gallery-transition`	`0.3s ease`	Transition timing for hover effects
`--rsl-gallery-overlay-bg`	`linear-gradient(...)`	Background gradient for overlay
`--rsl-gallery-focus-color`	`#6E7BFF`	Color for focus indicators
`--rsl-gallery-focus-shadow`	`0 8px 32px rgba(...))`	Box shadow for focus state

See FilterBus in Action

Watch how Gallery items show/hide based on filter selections. This live demo shows Filter + Smart Table + KPI Cards + Gallery + Charts all working together.

View Live Dashboard Demo

Back to Components View Examples Playground

Gallery Component