Skip to main content

Configuration

Here are the options you can pass to GridLanes. No options need to be specified, but itemSelector should be set.

Options that control layout — column widths, gutters, centering, RTL, buffer — are intentionally absent. Those belong in your CSS. See Getting started for the recommended container setup.

Options​

itemSelector [string]​

Default: '*'

CSS selector used to identify grid items inside the container. This should almost always be set.

new GridLanes(container, { itemSelector: '.picture-item' });

group [string | string[]]​

Default: 'all'

Initial filter group applied on construction. Pass 'all' or omit to show all items.

new GridLanes(container, { itemSelector: '.picture-item', group: 'nature' });

filterMode [string]​

Default: 'any'

Controls how array filters behave.

  • 'any' — item passes if it belongs to at least one of the given groups.
  • 'all' — item passes only if it belongs to every group in the array.
new GridLanes(container, { itemSelector: '.picture-item', filterMode: 'all' });

initialSort [SortOptions | null]​

Default: null

Sort to apply on initialization. It is the same object accepted by sort(). See Sorting below.

speed [number]​

Default: 250

Transition duration in milliseconds. Written to Grid Lanes' scoped View Transition rule while a transition starts.

new GridLanes(container, { itemSelector: '.picture-item', speed: 400 });

easing [string]​

Default: 'cubic-bezier(0.4, 0.0, 0.2, 1)'

CSS easing function for view transitions. Written to Grid Lanes' scoped View Transition rule while a transition starts.

new GridLanes(container, { itemSelector: '.picture-item', easing: 'ease-in-out' });

staggerAmount [number]​

Default: 15

Per-item animation delay offset in milliseconds. Each visible item gets an incremental delay based on its position in the sorted order. Grid Lanes writes a literal animation-delay rule per visible item's transition group while a transition starts.

staggerAmountMax [number]​

Default: 150

Maximum total stagger delay in milliseconds. The per-item delay is capped at this value when Grid Lanes writes the per-item group rules.

Page interactivity during transitions​

While a GridLanes transition captures snapshots, :root is temporarily excluded from snapshotting via an inline style. Without this, the root snapshot covers the viewport and clicks on the rest of the page are dispatched to the document element for the whole transition. With it, only named item and container snapshots participate, so filter buttons and other page controls stay clickable mid-transition. The exclusion lasts roughly one frame (until the transition's ready settles, including skipped transitions), is shared across overlapping GridLanes instances, and restores any pre-existing inline value afterwards. You can override it with an !important rule.

Rapid successive updates​

Updates are last-write-wins: if filter(), sort(), or update() is called while a transition is still running, the in-flight transition is skipped and the new state commits immediately. Skipping fast-forwards the old transition's animations to their end state, so rapid clicks visibly jump to the previous end state before the next transition begins. Only the latest state animates (intermediate states are not shown because they're skipped when a new one starts). At the default 250ms speed this is barely perceptible, but is more noticeable if you increase the transition duration.

Sorting object​

sort() and initialSort accept an object with the following properties:

by [(element: HTMLElement) => unknown]​

A function that receives the item's element and returns a value to sort by. Returning undefined reverts to original DOM order.

grid.sort({
  by: (element) => element.dataset.dateCreated,
});

compare [(a: GridLanesItem, b: GridLanesItem) => number]​

A custom comparator function. Receives two GridLanesItem objects (each with an .element property). Return negative to sort a before b, positive for the reverse.

grid.sort({
  compare: (a, b) => a.element.dataset.title.localeCompare(b.element.dataset.title),
});

reverse [boolean]​

Reverses the result of the by sort. Has no effect when used without by.

randomize [boolean]​

Randomizes item order.

grid.sort({ randomize: true });

API methods​

filter(category?)​

Filters all items to the given category. category can be:

  • A string: grid.filter('nature')
  • An array of strings: grid.filter(['nature', 'city'])
  • A predicate function: grid.filter((element) => element.dataset.featured === 'true')
  • 'all' or no argument: show all items

sort(sortObject?)​

Sorts the currently visible items. Pass null or an empty object to restore original DOM order.

update()​

Re-applies the current filter and sort. Useful after programmatically changing item data-groups.

layout()​

No-op in Grid Lanes mode. The browser handles geometry automatically. This method exists for API compatibility — it emits shuffle:layout via a microtask but does not trigger any layout recalculation.

add(newItems)​

Appends new items to the grid and applies the current filter and sort. newItems is an array of elements. Elements that are not already children of the container are automatically appended to it before being added to the grid.

remove(elements)​

Animates and removes one or more elements from the grid.

enable(runUpdate?)​

Re-enables the instance after disable(). If runUpdate is true (default), re-applies the current filter and sort immediately.

disable()​

Disables filter/sort/transition updates and aborts any in-flight transition.

resetItems()​

Re-queries itemSelector. Existing items keep their metadata; newly discovered elements are initialized. Use after dynamically adding items to the DOM without calling add().

getItemByElement(element)​

Returns the internal GridLanesItem for an element, or undefined if it is not tracked.

destroy()​

Removes all library-owned styles, classes, and event listeners. Does not remove the container's user-authored inline styles.

Events​

Listen with .on(eventName, handler) and stop listening with .off(eventName, handler). Use .once(eventName, handler) for one-time listeners.

shuffle:layout​

Fires after each committed filter or sort update. Always fires asynchronously — after ViewTransition.finished when view transitions are available, or in a microtask otherwise.

grid.on('shuffle:layout', ({ shuffle }) => {
  console.log('Layout complete', shuffle.sortedItems.length, 'visible items');
});

shuffle:removed​

Fires after removed items are physically removed from the DOM, immediately after the accompanying shuffle:layout event.

grid.on('shuffle:removed', ({ collection }) => {
  console.log('Removed', collection.length, 'items');
});