Quick Start

Reach a first working DnDGem layout as a React developer in about 10–15 minutes once packages are available to your app.

1. Install

npm install @dndgem/react@alpha

This pulls @dndgem/dom and @dndgem/core. For Vanilla DOM, install @dndgem/dom@alpha instead. Always use @alpha (0.1.0-alpha.0).

Do not use bare npm install @dndgem/react as the documented Alpha path while latest aliases the sole prerelease.

2. Minimal React board

import { DnDGemProvider, useDnDGem, useDnDGemContainer, useDnDGemItem } from '@dndgem/react';

const ITEMS = [
  {
    id: 'revenue',
    constraints: {
      minWidth: 96,
      minHeight: 64,
      minUsefulWidth: 140,
      preferredWidth: 180,
      preferredHeight: 88,
    },
  },
];

const DESIRED = {
  revenue: { x: 12, y: 12, width: 180, height: 88 },
};

function Board() {
  const containerRef = useDnDGemContainer();
  const { state, ready } = useDnDGem();
  const revenue = useDnDGemItem('revenue');

  return (
    <main>
      <p>{ready && state ? `${state.solver.evaluation.state} · ${state.phase}` : 'measuring…'}</p>
      <div
        ref={containerRef}
        style={{ position: 'relative', width: 480, height: 240, resize: 'both', overflow: 'hidden' }}
      >
        <article ref={revenue.ref} style={{ background: '#2f6f5e', color: '#fff', ...revenue.style }}>
          Revenue
        </article>
      </div>
    </main>
  );
}

export function App() {
  return (
    <DnDGemProvider items={ITEMS} desiredPlacements={DESIRED}>
      <Board />
    </DnDGemProvider>
  );
}

3. Rules that make this work

• Wrap the board in DnDGemProvider with items and desiredPlacements.
• Attach useDnDGemContainer() to a positioned containing block (position: relative).
• Merge …item.style after your visual styles so DnDGem owns geometry.
• Mount on the client — provider is not a full SSR path.
• Pointer drag and Escape cancel are supported; keyboard drag is deferred.

4. What you should see

• Items absolutely positioned from the resolved layout
• Status showing VALID (or DEGRADED when usefulness is missed)
• Pointer drag proposing a new layout through Core
• Container resize triggering measurement → reflow

Try the interactive demo: playground.dndgem.dev (provider URL: dndgem-playground.pages.dev).