Frameworks

Solid

@ogdakke/fluidbox/solid builds a gallery from parts: Fluidbox.Root owns one viewer, Fluidbox.Trigger opens it, and Fluidbox.Viewer, Fluidbox.Filmstrip and Fluidbox.Sheet render your components into it. It needs solid-js 1.8 or later.

Install#

pnpm add @ogdakke/fluidbox

npm install @ogdakke/fluidbox

yarn add @ogdakke/fluidbox

bun add @ogdakke/fluidbox

import { Fluidbox, useFluidbox, useFluidboxSheet } from "@ogdakke/fluidbox/solid";
import "@ogdakke/fluidbox/styles.css";

Import @ogdakke/fluidbox/styles.css once in your app. Fluidbox.Filmstrip and Fluidbox.Sheet turn their add-ons on by themselves. Each also needs its stylesheet, @ogdakke/fluidbox/filmstrip.css or @ogdakke/fluidbox/sheet.css.

A gallery#

import { For } from "solid-js";
import type { FluidboxImageItem } from "@ogdakke/fluidbox";
import { Fluidbox } from "@ogdakke/fluidbox/solid";
import "@ogdakke/fluidbox/styles.css";

const photos: FluidboxImageItem[] = [
  {
    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 },
  },
];

export function Photos() {
  return (
    <Fluidbox.Root items={photos}>
      <For each={photos}>
        {(photo) => (
          <Fluidbox.Trigger item={photo}>
            <img src={photo.thumbnail!.src} alt={photo.alt} />
          </Fluidbox.Trigger>
        )}
      </For>
    </Fluidbox.Root>
  );
}

With no Fluidbox.Viewer, the viewer has the default Previous, Next and Close buttons. 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>
  );
}

Parts#

All parts are properties of the Fluidbox object.

Fluidbox.Root#

TItem comes from items, so the events hand back your own item objects. The API reference describes the events and their reason.

Fluidbox.Trigger#

The preview accessor returns FluidboxTriggerPreview<TItem>: item: TItem | null, index: number | null and status. item is the item the trigger shows. While the viewer is open on item or one of returns, that is the item the viewer is on. Otherwise it is the last one the trigger showed. It is null when the trigger's items have left the list.

<Fluidbox.Trigger item={album[0]} returns={album}>
  {(preview) => <img src={preview().item?.src} alt={preview().item?.alt ?? ""} />}
</Fluidbox.Trigger>

The trigger adds data-fluidbox-trigger, aria-haspopup="dialog" and aria-expanded to its element, and starts loading the item on pointer down.

Fluidbox.ThumbnailOverlay#

It must be inside a Fluidbox.Trigger, and registers for that trigger's item and returns. It gets data-fluidbox-phase as the viewer opens and closes. With travel, its children also render live in the flying frame, under the same context.

Fluidbox.FrameLayer#

It goes inside a travelling ThumbnailOverlay and renders a <span data-fluidbox-frame-layer> with its children and span attributes. On each flight, the element itself moves into the flying frame, scales with it, and then goes back. Use it for a scrim or a border. The frame's live copy of the overlay leaves it out, so it never shows twice.

<Fluidbox.ThumbnailOverlay travel class="badge">
  <Fluidbox.FrameLayer class="scrim" />+{album.length - 1}
</Fluidbox.ThumbnailOverlay>

Fluidbox.Viewer and Fluidbox.Controls#

Fluidbox.Viewer takes only children and renders them into the viewer's layer while the viewer exists. While a Viewer is mounted, the viewer has no default controls. Put Fluidbox.Controls, or Previous, Next and Close, where you want them. Fluidbox.Controls takes no props.

Fluidbox.Previous, Fluidbox.Next, Fluidbox.Close#

Each takes button attributes. With no children it shows the default icon and an aria-label from labels. disabled follows the viewer's state: Previous and Next at the ends of a gallery that doesn't loop, Close while the viewer is closed. Pass disabled to override it. Your onClick runs first, and event.preventDefault() in it stops the command.

Fluidbox.Filmstrip#

The strip marks the selected button data-fluidbox-selected, so your thumbnail doesn't track the selection.

Fluidbox.Sheet and Fluidbox.SheetStop#

The runtime makes the sheet, a <section data-fluidbox-sheet> named by labels.sheet. The content renders straight into it with no wrapper of its own, and the section gets the Sheet's attributes. active is a FluidboxItemContext<TItem>, as a Filmstrip thumbnail's is. Fluidbox.SheetStop takes stop: number and button attributes. It is a button with data-fluidbox-sheet-stop, which works anywhere in the viewer. Pressed at its own stop, it lowers the sheet to 0.

Hooks#

Call them in a component inside Fluidbox.Root, including the content of Viewer, Sheet, Filmstrip and renderers.

The state fields of useFluidbox() are reactive getters, like Solid props. Read them in JSX or an effect, and don't destructure them. open takes the item, its id or its index. Commands return a Promise<boolean> that resolves true once the command happened, and false when it was prevented or superseded. A command made before the viewer exists waits for it. preload(target) starts loading an item a press is likely to open, and returns a function that lets go. load() loads the viewer's code now.

import { useFluidbox } from "@ogdakke/fluidbox/solid";

function Counter() {
  const fluidbox = useFluidbox();
  return (
    <button type="button" onClick={() => fluidbox.open(0)}>
      {fluidbox.index === null ? "Open" : `${fluidbox.index + 1} / ${fluidbox.count}`}
    </button>
  );
}

For a typed item, write useFluidbox<Photo>(), or annotate the selector: useFluidbox((state: FluidboxState<Photo>) => state.item).

Types#

The entry exports FluidboxRootProps, FluidboxTriggerProps, FluidboxTriggerPreview, FluidboxThumbnailOverlayProps, FluidboxFrameLayerProps, FluidboxViewerProps, FluidboxActionProps, FluidboxFilmstripProps, FluidboxSheetProps, FluidboxSheetStopProps, FluidboxItemContext, FluidboxSolidRenderer, FluidboxSolidRenderContext, FluidboxApi, FluidboxSheetApi and FluidboxSolidParts (the type of Fluidbox). It re-exports the item, list, label, origin, state and event types of @ogdakke/fluidbox, including FluidboxItemChangeEvent and FluidboxSheetEvent.

Patterns#

Solid notes#

Options apply live. Root makes its viewer once, in the browser. A change to labels or zoom goes to fluidbox.update(). So does mounting or unmounting a Filmstrip or Sheet, and changing the sheet's snapPoints or dismiss. An open viewer stays open, and only the filmstrip or sheet whose options changed draws again. Mounting or unmounting a Viewer swaps the viewer's controls in place. The binding reads origins, renderers and the event props when it uses them.

Reactive items. items is tracked: pass a signal's value (items={photos()}) and set a new array to change the gallery. An open viewer stays on the same item id if the new items still have it. useFluidbox().setItems does the same from inside.

Context reaches custom content. Renderers, travelling overlays and the viewer, filmstrip and sheet content render under Root, straight into the viewer's elements with no wrapper. Context provided around Root reaches them, as the Custom content example does with a theme, and so do the hooks.

as instead of asChild. The trigger renders its own element through Dynamic. Pass as="a" (with href) or a component. A component must forward ref and the event props (onClick, onPointerDown, onPointerUp, onPointerCancel) to a DOM element.

Event handlers. onClick and the pointer handlers may be a function or Solid's [handler, data] form. They run before the trigger's own, so event.preventDefault() in onClick stops the open. The trigger doesn't compose native on:click listeners with its own.

Server rendering. The parts render their markup on the server, and Root creates the viewer in an effect in the browser.

Previews update before the close flight. When the viewer closes on a different item of a multi-item trigger, the preview accessor updates synchronously so the flight lands on the right picture. The trigger finds its image when it registers, so keep the <img> mounted and change its src instead of swapping in a new element.