Vantage

Controlled grid layout builder for React. Drag, resize, restack, and compose sections on a responsive CSS grid. You bring every block component; Vantage handles layout chrome, breakpoints, and the data model.

Demo under demo/ — toolbar, layers, inspectors, context menu, persistence, seven block kinds:

cd demo && npm install && npm run dev

Install

Add as a git dependency:

"vantage": "git+https://git@github.com/dwrth/vantage.git"

npm i

prepare builds dist/ on install. No separate consumer build step.

Quick start

import { useState } from 'react';
import {
  VantageBuilder,
  VantagePreview,
  createEmptyLayout,
  defineKind,
  type Layout,
  type PreviewRendererProps,
  type EditRendererProps,
} from 'vantage';
import 'vantage/style.css';

type HeroData = { title: string; body: string };

function HeroPreview({ item }: PreviewRendererProps<HeroData>) {
  return (
    <div>
      <h2>{item.data?.title}</h2>
      <p>{item.data?.body}</p>
    </div>
  );
}

function HeroEdit({ item }: EditRendererProps<HeroData>) {
  return (
    <div>
      <h2>{item.data?.title}</h2>
      <p>{item.data?.body}</p>
      <span>Editing</span>
    </div>
  );
}

const heroKind = defineKind<HeroData>({
  component: HeroPreview,
  editComponent: HeroEdit,
  defaults: { w: 6, h: 4, label: 'Hero', data: { title: 'Hello', body: 'World' } },
  displayName: 'Hero',
});

const components = { hero: heroKind };

function App() {
  const [layout, setLayout] = useState<Layout>(createEmptyLayout);
  return (
    <>
      <VantageBuilder value={layout} onChange={(next) => setLayout(next)} components={components} />
      <VantagePreview value={layout} components={components} />
    </>
  );
}

Breakpoints, overrides, layers, persistence — all opt-in. Default: single-section desktop builder via createEmptyLayout().

Docs

Topic
Components	VantageBuilder, VantagePreview, defineKind
Layout model & mutations	Data shape, sections, items, layering, import/export
Breakpoints	Responsive overrides, resolution helpers
Selection	Controlled / uncontrolled selection
Section backgrounds	Color, image, blur, focal crop, parallax
Persistence	ref, strip/hydrate, kind persist hooks, file I/O
Undo / history	useVantageHistory, coalesce, reset
Custom blocks	defineKind patterns, interactivity, pitfalls
Theme / tokens	VantageThemeProvider, opaque CSS token maps
Host panels	VantageInspector, layers, toolbars (demo patterns)

Development

# library
npm install
npm run build      # dist/
npm run typecheck

# demo
cd demo
npm install
npm run dev        # http://localhost:5173