API reference

This page lists the full public surface of the three packages. The guides cover the concepts; this is the lookup table. All three packages are ESM-only ("type": "module" with an exports map), so your tsconfig needs moduleResolution: "bundler", "node16", or "nodenext". Classic "node" resolution cannot find them. @dashfoo/react ships a "use client" banner, so it works as a client component in the Next.js App Router without a wrapper.

@dashfoo/reactCopy Anchor Link

The React binding: DashfooLayout, the Panel compound parts, the hooks, and the storage adapters. Source: packages/react/src.

DashfooLayout propsCopy Anchor Link

The component props. The props are a union: pass either model (controlled) or defaultModel (uncontrolled), never both and never neither. persist only exists on the defaultModel side. All three rules are enforced by the type, so the combinations that used to type-check and silently do nothing no longer compile. DashfooLayoutCommonProps is exported for helpers that spread overrides.

The model's global block layers under the boolean props: a feature is on only if neither the prop nor the global (tabEnableClose, tabEnableRename, tabSetEnableMaximize, tabEnableDrag, enableSplitResize) turns it off, and (for everything except maximize) only while editable is on. The root element is <div data-dashfoo="layout"> at 100% of its parent in both axes. A parent without a real height paints nothing (see getting started).

Static layoutsCopy Anchor Link

editable={false} freezes the arrangement in one move: tabs and tabsets cannot be dragged, tabs cannot be closed or renamed, splitters stop resizing (they stay mounted, so nothing reflows), and the layout rejects drops from useExternalTabSource, even under a shared DashfooDragProvider while a sibling layout stays editable. The dashboard remains interactive as a viewer: tab selection, keyboard tab navigation, the overflow menu, and maximize/restore remain available, and the imperative DashfooHandle / dispatch API still mutates the model programmatically. Flip the prop at runtime to build an "edit mode" toggle without a remount.

DashfooHandleCopy Anchor Link

A ref on DashfooLayout exposes 14 imperative methods.

import type { TabNode } from "@dashfoo/core";
import { model, row, tab, tabset } from "@dashfoo/core";
import type { DashfooHandle } from "@dashfoo/react";
import { DashfooLayout } from "@dashfoo/react";
import type { ReactNode } from "react";
import { useRef } from "react";

const Notes = ({ node }: { node: TabNode }): ReactNode => <div>{node.name}</div>;

const initial = model(row([tabset([tab("notes", "Notes")], { id: "main" })]));

const App = (): ReactNode => {
  const ref = useRef<DashfooHandle>(null);
  const handleAdd = (): void => {
    // ids default to the component name; pass an explicit id for a duplicate.
    ref.current?.addTab(tab("notes", "Scratch", { id: "notes-2" }), {
      location: "split-right",
      targetId: "main",
    });
  };
  return (
    <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
      <button onClick={handleAdd} type="button">
        Add tab
      </button>
      <div style={{ flex: 1, minHeight: 0 }}>
        <DashfooLayout components={{ notes: Notes }} defaultModel={initial} ref={ref} />
      </div>
    </div>
  );
};

export { App };

See controlled & history for the controlled-mode pairing and undo/redo wiring.

Panel compound partsCopy Anchor Link

Unstyled building blocks for panel content. Each forwards its native props and adds a data-dashfoo attribute for styling.

Prop types are exported as PanelRootProps, PanelHeaderProps, PanelBodyProps, PanelTitleProps, PanelIconProps, and PanelBadgeProps.

Layout and Tabset compound partsCopy Anchor Link

The primitives DashfooLayout itself is built from, exported for hand-built layouts. Layout.Root (the frame + layout store), Layout.DragLayer (drag-dock, optional), Layout.Rows (the split tree, with a renderTabset render prop), Layout.Tabset (the stock tabset composition), and, for floating panels, Layout.FloatLayer (wrap the tree's content, passing floats + global, to render each floated panel as a draggable overlay). Plus the full tabset decomposition under Tabset.*: Root, TabStrip, Tablist, Tab, Trigger, RenameInput, CloseButton, Content, Toolbar, OverflowMenu, Grip, MaximizeButton, and FloatButton. Each part spreads native props and is unstyled beyond minimal structural flex. See Build your own layout for the part table and a complete example.

useDashfooStoreCopy Anchor Link

The store DashfooLayout uses internally, exposed for hosts that render their own chrome. Throws when given neither model nor defaultModel; every entry point is normalized.

UseDashfooStoreOptions:

Returns a DashfooStore:

useLayoutCopy Anchor Link

Selector hook over the layout store: the layout's resolved configuration and dispatch, for custom chrome (a renderTabsetToolbar button, a custom tab label). useLayout((state) => state.dispatch) re-renders only when the selected slice changes. Throws outside <DashfooLayout> / <Layout.Root>. The LayoutState fields:

useTabset / useTab / useDragSubject / useDropIntentCopy Anchor Link

useTabset((state) => …) selects from the per-tabset store inside <Tabset.Root>: node, visualSelected, activeTab, isMaximized, editingTabId, overflowItems, the resolved flags (tabsClosable, tabsRenamable, showMaximize), and the actions (selectTab, closeTab, renameTab, startEditing, toggleMaximize, selectOverflowTab).

useTab() returns { tab, index } (which tab the part belongs to) inside <Tabset.Tab>.

useDragSubject() returns the live drag subject ({ kind: "tab" | "tabset" | "external", id }) or null, including outside a drag layer. See Build your own layout.

useDropIntent() returns the live drop intent ({ targetId, location, index? }, where the drag would land if dropped right now) or null when nothing is dragging or the pointer is over no valid target (empty space, a non-editable layout, or a suppressed no-op drop). Both hooks work anywhere under a layout; under a DashfooDragProvider they work anywhere under the provider. Pair with dockZonePolygons from @dashfoo/core for custom drop indicators and drop-zone visualizations.

usePersistenceCopy Anchor Link

The load/save half behind the persist prop, usable standalone. usePersistence(config: PersistConfig | null, defaultModel: Dashfoo | undefined)

It loads the saved model once (validated; falls back to defaultModel on miss or corruption, pruning corrupt values with a warning), debounce-saves every change, and flushes a pending save on page hide (pagehide / visibilitychange → hidden) and on unmount. A null config makes it a no-op. initialModel starts as the seed, then updates after mount when storage is restored. Hosts that create a store once must apply that update with setModel; persist on DashfooLayout already does this without a history entry or a save.

Storage adaptersCopy Anchor Link

External drag sourcesCopy Anchor Link

Drag new tabs in from outside the layout. See drag & dock for the full flow.

useContainerWidthCopy Anchor Link

() => [ref: (el: HTMLElement | null) => void, width: number] tracks one element's content-box width via ResizeObserver. SSR-safe: seeds POSITIVE_INFINITY so the first render assumes the widest layout. The building block for hand-built responsive layouts (pair with stackModel).

useResponsiveModelCopy Anchor Link

Picks a model per breakpoint, keyed off the container's own width (ResizeObserver) and/or media queries, and derives the structural-interaction flags from the active breakpoint's compact. Feed the result onto DashfooLayout/Layout.Root as reactive props; no key or remount is needed. SSR-safe. See responsive.

@dashfoo/coreCopy Anchor Link

The framework-free engine: schema, builders, actions, reducer, tree queries, geometry, history, serialization, and the XState machines. Source: packages/core/src.

ActionsCopy Anchor Link

Every document mutation is one of 18 immutable, discriminated actions. The reducer is exhaustive over the union; validate untrusted payloads with actionSchema before dispatch.

Related exports: actionSchema, dockLocationSchema, mutableNodeAttrsSchema, and the types Action, MutableNodeAttrs, DockLocation ("center" | "split-top" | "split-bottom" | "split-left" | "split-right"), and DropIntent ({ targetId: string; location: DockLocation; index?: number }). See drag & dock for how drops become actions.

BuildersCopy Anchor Link

Constructors that fill the mechanical fields (type, version, selected, weight, floats) so seed models stay short.

Option types: TabOptions (config, enableClose, enableDrag, enableRename, id), TabsetOptions (enableClose, enableMaximize, id, max, min, name, selected, weight), RowOptions (id, max, min, orientation, weight), ModelOptions (activeTabsetId, floats, global, maximizedTabsetId), FloatOptions (id, name). min/max accept a bare number (treated as px) or a Dimension.

SchemaCopy Anchor Link

Zod schemas and their inferred types. Field-by-field tables live in the model guide.

DashfooInput (z.input<typeof dashfooSchema>) is the loose counterpart of Dashfoo: the shape parseModel accepts, with weight and floats optional. Hold host-supplied or stored data as DashfooInput and parse it into a Dashfoo. tabsetNodeObjectSchema is tabsetNodeSchema before its clamping transform, for .pick()-ing mutable keys off.

Node (RowNode | TabsetNode | TabNode) is exported as a type only. FloatNode ({ type: "float"; id; layout: RowNode; geometry: Geometry; name?; minimized? }) holds a floating panel; see floating panels. The model's version is the pinned literal 1; payloads with any other version fail validation.

Reducer and normalizeCopy Anchor Link

Tree helpersCopy Anchor Link

Read-only queries over a model. All of them take the whole model and span every root, so a floated node is as reachable as a docked one. Matching is predicate-first: an id that also names a node of another kind cannot make two of these disagree about which node wins.

Types: AttributedNode, TabContainer, TabLocation.

IdsCopy Anchor Link

stackModelCopy Anchor Link

stackModel(model: Dashfoo, orientation: Orientation = "column"): Dashfoo flattens any layout into a single row of all its tabsets in document order, each with equal weight, and clears maximize. It is the building block for a mobile breakpoint. See responsive.

GeometryCopy Anchor Link

Types: Point ({ x: number; y: number }), Rect ({ x: number; y: number; width: number; height: number }), BandOptions ({ bandFraction?: number }).

HistoryCopy Anchor Link

Past/present/future snapshots over the reducer. Every dispatched action is one undo step; there is no coalescing. A splitter drag is still a single step because react-resizable-panels v4 commits one adjustSplit per release.

History is { past: Array<Dashfoo>; present: Dashfoo; future: Array<Dashfoo> }.

SerializationCopy Anchor Link

MachinesCopy Anchor Link

Two XState machines, for hosts that bypass the React binding.

• dashfooMachine: the document actor. Input { model: Dashfoo }, context { history: History }. Events: DISPATCH ({ action }), UNDO, REDO, and SET_MODEL ({ model }, which resets history). Its context and event unions are internal and not exported.
• dragDockMachine: the drag/dock interaction lifecycle. Events: START ({ subject: DragSubject }), OVER ({ drop: DropResolution | null }), DROP, CANCEL. Its context is one DragState ({ kind: "idle" } | { kind: "dragging"; subject; drop }), so a drop target without a subject is unrepresentable. A valid drop emits { type: "COMMIT", action, scope }, where scope echoes back the DropResolution.scope that resolved the intent so the host can route the action: moveNode for a tab drag, moveTabset for a tabset-grip drag; addNode only for an external source. dropAction(drag) is the same decision as a plain function. Types: DragState, DragSubject, DropResolution.

@dashfoo/themeCopy Anchor Link

The opt-in default skin over --dashfoo-* tokens, light by default, dark via data-dashfoo-theme="dark" on any ancestor. The full token table is in theming.

The only JS export is DASHFOO_THEME_VERSION, a version constant for runtime checks.