Frameworks

JavaScript

The package root, @ogdakke/fluidbox, runs the viewer without a framework or custom elements. createFluidbox() makes a fluidbox, which is one viewer at the end of <body> plus the state, commands and events that drive it. fluidbox.bind() makes an element open it.

Install#

pnpm add @ogdakke/fluidbox

npm install @ogdakke/fluidbox

yarn add @ogdakke/fluidbox

bun add @ogdakke/fluidbox

import { createFluidbox } from "@ogdakke/fluidbox";
import "@ogdakke/fluidbox/styles.css";

Import @ogdakke/fluidbox/styles.css once in your app. The filmstrip and the sheet are add-ons, covered in Add-ons.

A gallery#

import { createFluidbox, type FluidboxItem } from "@ogdakke/fluidbox";
import "@ogdakke/fluidbox/styles.css";

const photos: FluidboxItem[] = [
  {
    type: "img",
    src: "/photos/dune.jpg",
    alt: "Dune at dusk",
    width: 1800,
    height: 1200,
    thumbnail: { src: "/photos/dune-400.jpg", width: 400, height: 267 },
  },
  {
    type: "img",
    src: "/photos/fjord.jpg",
    alt: "Fjord",
    width: 1200,
    height: 1600,
    thumbnail: { src: "/photos/fjord-400.jpg", width: 400, height: 533 },
  },
];

const fluidbox = createFluidbox({ items: photos });

// Each <button> in .gallery holds its thumbnail <img>, in the order of `photos`.
document.querySelectorAll<HTMLButtonElement>(".gallery button").forEach((button, index) => {
  fluidbox.bind(button, index);
});

The viewer has Previous, Next and Close buttons until you draw your own with viewer. To keep some of them next to yours, pass controls: true or a list such as ["close"]. The same gallery, live, in every framework:

ReactVueSolidAngularElementsJavaScript

Loading the live example…

basic.tsx

import { itemLabel } from "@ogdakke/fluidbox";
import { Fluidbox } from "@ogdakke/fluidbox/react";
import { photos } from "./data";

export function Basic() {
  return (
    <Fluidbox.Root items={photos}>
      <div className="pattern-grid">
        {photos.map((photo) => (
          <Fluidbox.Trigger
            key={photo.src}
            item={photo}
            className="pattern-thumb"
          >
            <img src={photo.src} alt={itemLabel(photo)} />
          </Fluidbox.Trigger>
        ))}
      </div>
      {/* Without a Viewer, the viewer has these same three buttons. */}
      <Fluidbox.Viewer>
        <Fluidbox.Previous />
        <Fluidbox.Next />
        <Fluidbox.Close />
      </Fluidbox.Viewer>
    </Fluidbox.Root>
  );
}

createFluidbox(options)#

Returns a Fluidbox. Only items is required.

To change labels, zoom, controls, viewer, filmstrip, sheet or loading, call update. The open viewer stays open. To change the items, call setItems. The fluidbox looks up renderers by name each time a custom slide mounts, and reads origins on each use.

The fluidbox#

A target is an item, its index or its id. The fluidbox matches an item object by its id, so a copy of it works too. The fluidbox is an EventTarget, with the events listed below.

update#

update(options) changes options on the live viewer, without closing it. A key you leave out keeps its value; a key set to undefined goes back to its default:

const coarse = matchMedia("(pointer: coarse)");
coarse.addEventListener("change", () => {
  fluidbox.update({ zoom: coarse.matches ? false : undefined });
});
fluidbox.update({ labels: { close: "Sulje", previous: "Edellinen", next: "Seuraava" } });

Labels and zoom apply in place. A change of controls, viewer or the labels draws the viewer's layer again, and a change of filmstrip or sheet mounts that add-on again. update compares options objects member by member and functions by identity, so pass the same viewer and render functions from one call to the next.

Commands#

A target, FluidboxTarget, is an item, its index or its id: open(photo), open(2) or open("photo-fjord"). options is { signal?: AbortSignal, scrub?: boolean }. Use scrub: true for a move that follows a continuous input, such as your own scrubber or a dragged row of dots. The slide jumps to the item instead of gliding. The fluidbox doesn't scroll the page to the item's trigger until the next move without scrub, which ends the scrub.

Each command returns a promise that settles when the motion has: open once the viewer is open, close once it is closed, next once the slide has moved. It resolves true when the command happened. It resolves false when a listener prevented it, a later command took over, its signal aborted, or there was nothing to do, as with next() on the last item of a gallery that doesn't loop, or close() while closed.

An unknown id or an index out of range rejects with a RangeError, and preload throws one. After destroy(), the commands and load() resolve false, so a part of your app still holding the old fluidbox does nothing. setItems, preload, bind, bindOverlay and subscribe throw an InvalidStateError DOMException.

State#

interface FluidboxState<TItem> {
  readonly status: "closed" | "opening" | "open" | "closing";
  readonly id: string | null;
  readonly index: number | null;
  readonly item: TItem | null;
  readonly count: number;
  readonly hasPrevious: boolean;
  readonly hasNext: boolean;
}

id, index and item are the item the viewer shows, or is on its way to while a move runs, and null while closed. item is your own object, the one you passed in. hasPrevious and hasNext say whether previous() and next() have somewhere to go. With loop, both are true in a gallery of two or more. subscribe sees status and selection changes. It doesn't see motion, which runs frame by frame in CSS variables. Styling lists them.

Events#

Listen with addEventListener. The events are typed, so event.reason and event.item need no casts:

oldState and newState are "open" or "closed", as on a popover's toggle events. reason, a FluidboxReason, says what asked:

The before-events fire for every command that would do something, whether it comes from a key, a gesture or your code. close() while closed or next() on the last item fires nothing. An open fires beforetoggle, toggle and itemchange, then settle after the flight. Then the promise resolves.

fluidbox.addEventListener("beforeitemchange", (event) => {
  if (event.reason === "wheel") event.preventDefault();
});
fluidbox.addEventListener("settle", ({ id }) => {
  history.replaceState(null, "", `#${id}`);
});

Triggers#

fluidbox.bind(element, target, options?) makes an element a trigger. It registers the element as its item's origin, so the flight starts and lands there. It loads the viewer's code as loading says, starts loading the item on pointer down, and opens the viewer on click unless a listener prevented the click. It adds data-fluidbox-trigger, aria-haspopup="dialog" and aria-expanded to the element. Use an element that can take focus, such as a <button>. It returns a function that unbinds.

The flight uses the trigger's first image, or an element inside it marked data-fluidbox-origin. Which element the flight uses has the rules.

One trigger for several items#

List more items in returns, and one element stands for all of them, as an album cover does. The viewer opens on the target, and the target and every item in returns close back onto the element. returns may hold the whole album, the target included. After a close, a click opens the item the trigger last showed, so the flight starts from the picture on it:

fluidbox.bind(cover, album[0], {
  returns: album,
  onPreviewChange(item) {
    coverImage.src = item.thumbnail?.src ?? coverImage.src;
  },
});

One trigger for an album shows it in every framework.

Bindings follow setItems. An id that leaves the list stops being the trigger's until it comes back, and an index names whichever item is at that index now, so bind by id where the list reorders.

Thumbnail overlays#

A badge, a play icon or a count on a thumbnail can follow the flight. fluidbox.bindOverlay(element, target, options?) makes an element inside a trigger a thumbnail overlay. As the viewer opens and closes, the element gets --fluidbox-closed, from 1 at the thumbnail to 0 fully open, and data-fluidbox-phase. Without travel, it stays on the page.

// The count flies with the photo and fades as it lands.
fluidbox.bindOverlay(count, album[0], { returns: album, travel: true });

// Live content: the renderer draws into the flying frame for each flight.
fluidbox.bindOverlay(badge, "clip", {
  travel: ({ item, target }) => {
    const label = document.createElement("span");
    label.className = "badge";
    label.textContent = item.type === "video" ? "Video" : "";
    target.append(label);
  },
});

The travelling content and the frameLayer scale with the flying frame, so their boxes match it. Their direct children scale back, so they keep the size they had on the thumbnail. A child scales back around the edge it sits against (left, right, top or bottom) or around its centre, so a corner badge stays in its corner and a centred label stays centred. Size children by their content. A child stretched to the box's width ends up as wide as the full-size frame. While the flight starts, the page shows a still copy of the frameLayer, marked data-fluidbox-ghost, in the thumbnail.

The renderer gets { item, index, target, signal }, like any renderer. See Styling for the CSS hooks.

Viewer content#

The viewer's layer is yours to fill. The viewer option draws into it when the fluidbox is made, and again after an update that changes the layer:

Return a function to clean up, such as the one subscribe returns. Everything in the layer hides during the opening flight and fades out as a close or a drag starts, like the default controls. controls and viewer combine, with the default buttons first and yours after.

import { createFluidbox } from "@ogdakke/fluidbox";

const fluidbox = createFluidbox({
  items: photos,
  controls: ["close"],
  viewer({ target, fluidbox }) {
    const caption = document.createElement("p");
    caption.className = "caption";
    target.append(caption);
    return fluidbox.subscribe(({ item }) => {
      if (item?.type === "img") caption.textContent = item.alt;
    });
  },
});

The default buttons carry data-fluidbox-previous, data-fluidbox-next and data-fluidbox-close. Any button in the viewer with one of them runs that command, gets the default styling, and is disabled while the command can do nothing. Call event.preventDefault() in your own click listener to stop the command. Headless controls has a full caption bar in every framework.

Add-ons#

The filmstrip and the sheet have their own entries. Turn one on with its option and the fluidbox loads its entry; import the entry to bundle it up front:

import { createFluidbox } from "@ogdakke/fluidbox";
import "@ogdakke/fluidbox/filmstrip";
import "@ogdakke/fluidbox/filmstrip.css";
import "@ogdakke/fluidbox/sheet";
import "@ogdakke/fluidbox/sheet.css";

const fluidbox = createFluidbox({
  items: photos,
  filmstrip: true,
  sheet: {
    snapPoints: ["40%", "90%"],
    render({ item, target }) {
      target.textContent = item.id ?? "";
    },
  },
});

An open waits for an entry that is still loading. Filmstrip and sheet has every option.

Patterns#

Notes#

Server rendering. Importing @ogdakke/fluidbox has no side effects and touches no browser globals, so it is safe on the server. createFluidbox() needs document.

Clean up. Call destroy() when the gallery leaves the page. It releases every binding too, so the functions bind returns are for unbinding one trigger early.

Your own fields. Items can carry fields of your own: createFluidbox<Photo>({ items }) with interface Photo extends FluidboxImageItem { caption: string }. Every callback, event and state hands back your object, so state.item.caption is typed.