@slithy/justified-gallery

A vanilla TypeScript rewrite of Justified Gallery by Miro Mannino. No jQuery, no dependencies.

Arranges images into rows of equal height, scaling each proportionally so rows fill the container edge to edge — the same layout style used by Flickr, Google Photos, and 500px.

Installation

npm install @slithy/justified-gallery

Usage

import { justifiedGallery } from '@slithy/justified-gallery'
import '@slithy/justified-gallery/css'

justifiedGallery('#my-gallery', { rowHeight: 200 })

justifiedGallery accepts an element or a CSS selector. Calling it again on the same element updates settings and re-lays-out:

const jg = justifiedGallery('#my-gallery', { rowHeight: 200 })

justifiedGallery('#my-gallery', { rowHeight: 160 }) // update + re-layout

jg.destroy()

Options

| Option | Type | Default | Description | |---|---|---|---| | sizeRangeSuffixes | Record<number, string> | {} | Map of max pixel size → filename suffix (Flickr-style thumbnails). | | thumbnailPath | (src, width, height, image) => string | — | Custom thumbnail URL resolver. Overrides sizeRangeSuffixes when set. | | rowHeight | number | 120 | Target row height in pixels. | | maxRowHeight | number \| string \| false | false | Max row height: px number, percentage string (e.g. '150%'), or false to disable. | | maxRowsCount | number | 0 | Maximum number of rows to display. 0 = no limit. | | margins | number | 1 | Gap between entries in pixels. | | border | number | -1 | Outer border in pixels. -1 = same as margins, 0 = none. | | lastRow | 'justify' \| 'nojustify' \| 'left' \| 'center' \| 'right' \| 'hide' | 'nojustify' | How the last (incomplete) row is treated. | | justifyThreshold | number | 0.90 | Justify a row when its fill ratio exceeds this threshold, regardless of lastRow. | | waitThumbnailsLoad | boolean | true | Wait for thumbnails to load before laying out. | | captions | boolean | true | Show captions on hover. | | rel | string \| null | null | Rewrite the rel attribute of each entry link. null = leave as-is. | | target | string \| null | null | Rewrite the target attribute of each entry link. null = leave as-is. | | extension | RegExp | /\.[^.\\/]+$/ | Matches the file extension in image URLs. | | refreshTime | number | 200 | Interval (ms) for checking container width changes. | | refreshSensitivity | number | 0 | Width delta (px) that triggers a re-layout. | | randomize | boolean | false | Randomize entry order. | | rtl | boolean | false | Right-to-left layout. | | sort | (a: Element, b: Element) => number \| false | false | Sort comparator, or false to disable sorting. | | filter | string \| ((entry, index, array) => boolean) \| false | false | CSS selector string or filter function, or false to disable. | | selector | string | 'a' | CSS selector identifying gallery entries. | | imgSelector | string | '> img, > a > img, > svg, > a > svg' | CSS selector identifying the image within each entry. | | triggerEvent | (this: instance, event: string) => void | internal | Called to dispatch gallery events. Override to use a custom event system. |

Instance methods

The object returned by justifiedGallery(...) (also available via new JustifiedGallery(element, settings)) exposes:

| Method | Description | |---|---| | refresh(newSettings?) | Re-layout the gallery, optionally applying new settings first. Equivalent to updateSettings + rewind + updateEntries + init. | | addEntries() | Pick up entries added to the DOM since the last layout pass without rewinding existing rows. Use for infinite scroll. | | updateSettings(settings) | Merge new settings into the current ones, without re-running the layout. | | rewind() | Reset internal layout state, forcing a full re-layout on the next init(). | | updateEntries(norewind) | Re-scan the container for entries. | | init() | Run (or re-run) the layout pass. | | destroy() | Remove all layout styles and event listeners, restoring the element to its pre-initialized state, and fire the jg.destroy event. |

Events

Gallery events are dispatched as CustomEvent on the gallery element:

| Event | Fired when | |---|---| | jg.complete | All entries have been laid out. | | jg.resize | The layout has been recalculated after a resize. | | jg.rowflush | A new row has been positioned. | | jg.destroy | destroy() has completed. |

document.querySelector('#my-gallery').addEventListener('jg.complete', () => {
  console.log('gallery ready')
})

To use a custom event system, override triggerEvent in settings:

justifiedGallery('#my-gallery', {
  triggerEvent(event) {
    myBus.emit(event, this)
  },
})

Types

import type {
  Settings,
  SettingsInput,
  EntryData,
  LastRowMode,
  ThumbnailPathFn,
  SortFn,
  FilterFn,
  TriggerEventFn,
  JustifiedGalleryInstance,
} from '@slithy/justified-gallery'

• Settings — Full settings object (see Options).
• SettingsInput — Partial<Settings>, accepted at construction/update time.
• EntryData — Per-entry layout state tracked internally (load status, natural/justified dimensions, etc.).