Drag-and-drop for
server-rendered pages.

STEP 01 / GET STARTED

Install

Download the prebuilt release archive, then serve one surface bundle or the full kit alongside the open-source Datastar + Rocket runtime. Each surface includes its own core dependencies; the core bundle is also available for custom mechanics. Render the tags and data attributes from any backend.

mkdir -p public/js
curl -fsSL "https://github.com/<owner>/<repo>/releases/latest/download/pd-rockets-browser.tar.gz" | tar -xz -C public/js
# serve the upstream datastar-rocket.js at /js/datastar-rocket.js
<script type="importmap">{"imports":{"pd-rockets/rocket":"/js/datastar-rocket.js"}}</script>
# choose one of the following:
<script type="module" src="/js/rocket-sortable-tree.js"></script>
<script type="module" src="/js/rocket-kit.js"></script>

Get the Rocket runtime ↗ · Upstream MIT notice ↗

The import map resolves pd-rockets/rocket to the pinned upstream module. If your page supplies a separate Rocket ES module, map that specifier to its URL instead; it must export rocket and use the same Datastar instance as the page. The guide uses the latest pinned upstream Datastar + Rocket bundle (v1.0.4) with its MIT notice.

• rocket-core.js ↓ (7.0 kB br) .br ↓
• rocket-kanban.js ↓ (4.3 kB br) .br ↓
• rocket-sortable-list.js ↓ (3.8 kB br) .br ↓
• rocket-drag-group.js ↓ (4.1 kB br) .br ↓
• rocket-bento-workspace.js ↓ (5.9 kB br) .br ↓
• rocket-sortable-tree.js ↓ (4.6 kB br) .br ↓
• rocket-context-menu.js ↓ (3.2 kB br) .br ↓
• rocket-inline-edit.js ↓ (0.6 kB br) .br ↓
• rocket-kit.js ↓ (16.1 kB br) .br ↓

Sizes are Brotli-compressed kilobytes (1 kB = 1,000 bytes). Use the regular .js file in script tags; the optional .br file is for servers configured to serve precompressed JavaScript with Content-Encoding: br.

PD rockets license ↓

STEP 02 / LIVE EXAMPLE

Kanban board

Each lane carries a numeric data-col; cards carry stable IDs. Drag a card into another lane, or focus a card and press Alt+→. The emitted event describes the target lane and the card to insert before; it does not perform a mutation. Plain arrows navigate focus; use Alt+h/j/k/l to stage keyboard moves, then release Alt to commit.

<rocket-kanban-board>
  <section data-kanban-lane data-col="0">
    <div data-kanban-lane-cards>
      <article data-kanban-card="card-a" tabindex="0">
        <button data-kanban-card-main>Card title</button>
      </article>
    </div>
  </section>
</rocket-kanban-board>

rocket-kanban-move → { cardId, col, before }

Kanban Rocket source ↗ · JSX template ↗

STEP 03 / LIVE EXAMPLE

Sortable list

A sortable list uses the shared pointer lifecycle but chooses its own target geometry and semantic event. Drag above or below an item to insert at that position. Up/down arrows or j/k navigate focused items; Home/End jump to the first or last item. Alt + up/down stages a reorder; release Alt to commit or press Escape to cancel.

<rocket-sortable-list>
  <div data-sortable-item="list-a" tabindex="0">First item</div>
  <div data-sortable-item="list-b" tabindex="0">Second item</div>
</rocket-sortable-list>

rocket-sortable-move → { itemId, before }

Sortable Rocket source ↗ · JSX template ↗

STEP 04 / LIVE EXAMPLE

Move between lists

A drag group coordinates several lists without assigning Kanban columns or card semantics. Move an item within a list or into another list, including the space after its last item. Each group is its own drag scope; the page decides how to apply the emitted move. Plain arrows move focus within and between lists. Focus an item and use Alt + arrows (or h/j/k/l), then release Alt to commit. Escape cancels the staged move.

<rocket-drag-group>
  <section data-drop-list="inbox">
    <div data-drag-item="note-a" tabindex="0">Sketch a card</div>
  </section>
  <section data-drop-list="later"></section>
</rocket-drag-group>

rocket-drag-group-move → { itemId, fromList, toList, before }

Drag group Rocket source ↗ · JSX template ↗

COMPOSITION / LIVE EXAMPLE

Nested Rockets

A sortable list sits inside an item of a drag group. Drag or use Alt + arrows on an inner item to reorder only that list; drag the outer item to move the whole group item. Each host emits its own event, and the page patches the matching example over SSE. Semantic events still bubble; when nesting two hosts of the same surface, the page should check the event target before invoking an outer action.

Host ownership source ↗ · Pointer lifecycle ↗

STEP 05 / LIVE EXAMPLE

Bento grids

Two CSS grids share one drag scope. Drop a tile on a cell in either grid, or use its ↘ handle to resize it. Displaced tiles preview their new cells while you drag or resize. Rocket sends every changed position on commit; the backend applies them and returns HTML. Plain arrows navigate tiles within and across grids with arrows or h/j/k/l. Focus a tile: Alt + arrows move it by a cell and cross a board boundary at an edge; Alt + Page Up/Down switches grids directly, and Shift + arrows resize. Release the modifier to commit; Escape cancels.

The browser proposes positions for its live preview. The synthetic backend checks the complete resulting grid for bounds and overlap before accepting them; a consuming backend validates its own layout rules.

<rocket-bento-workspace>
  <div data-bento-grid="overview" data-columns="4">
    <article data-bento-item="tile-a" data-bento-col="1" data-bento-row="1"
      data-bento-width="2" data-bento-height="2" tabindex="0">
      Traffic <button data-bento-resize aria-label="Resize Traffic">↘</button>
    </article>
  </div>
  <div data-bento-grid="scratchpad" data-columns="4"></div>
</rocket-bento-workspace>

rocket-bento-move → { itemId, fromGrid, toGrid, updates: [{ itemId, grid, col, row, width, height }] }
rocket-bento-resize → { itemId, grid, updates: [{ itemId, grid, col, row, width, height }] }

Bento Rocket source ↗ · Placement rule ↗ · JSX template ↗

STEP 06 / LIVE EXAMPLE

File tree

Reorder files and folders, or drop onto a folder to move an entry inside it—even when it is empty. Nested entries move with their folder. Plain up/down arrows (or j/k) navigate visible rows; right expands or enters a folder, and left collapses it or returns to its parent. Focus a row: Alt + up/down reorders among siblings, Alt + right moves it into the preceding folder, and Alt + left moves it out. At the first or last child, Alt + up/down also moves it before or after the parent folder. Release Alt to commit; Escape cancels.

<rocket-sortable-tree>
  <div data-tree-children data-tree-parent="">
    <div data-tree-node="src" data-tree-kind="folder">
      <div data-tree-row tabindex="0">src</div>
      <div data-tree-children data-tree-parent="src">…files…</div>
    </div>
  </div>
</rocket-sortable-tree>

rocket-tree-move → { itemId, fromParent, toParent, before }

Tree Rocket source ↗ · JSX template ↗

STEP 07 / SERVER HANDOFF

Server round trip

Bind each semantic event to a Datastar action in your page. Your server handler validates the target, updates authoritative state, and sends complete HTML over SSE. On this page, a site-only fetch shim stands in for that handler and returns a datastar-patch-elements event. Datastar performs the morph; Rocket animates items from their prior positions to the new ones. Try a demo gesture: the small activity queue shows the Rocket event, the Datastar POST and the SSE patch returned by the fixture, without recording item text or request content.

event: datastar-patch-elements
data: selector #kanban-demo
data: mode outer
data: elements <div id="kanban-demo">…complete example…</div>

Browser fixture source ↗ · Go SSE handler ↗

The page seeds only interaction-detail signals. Board, list and grid content live in rendered DOM, not signals.

STEP 08 / YOUR DESIGN SYSTEM

Make it yours

Pick the surface bundle you need and render its light-DOM contract with your own components, classes, and content. PD rockets supplies interaction behavior, not a required stylesheet. Keep the host tag, stable item IDs, focusable items, and the data-* hooks; style everything around them to fit your product.

If your HTML morph keys elements by DOM id, give each card a stable, board-scoped ID too. That keeps an in-flight animation attached to the same card when another card leaves its lane.

Your server-rendered markup is the design surface. Use your own component classes and CSS custom properties for colors, spacing, and shape; Rocket’s data-* attributes expose the interaction states. There is no mandatory theme or token set.

Move a card between channels: the demo’s page-owned handler updates its model and morphs confirmed markup over SSE. The moving hologram and destination label are rendered from the two template outlets below. The animated backdrop is a decorative canvas; cards, focus, and drag targets remain HTML. See the canvas source ↗ and theme CSS ↗.

This is a rocket-drag-group with a playful destination. The page handler interprets a move to bin as deletion, then returns the remaining HTML over SSE. The poof is decoration; the model change is confirmed by the morph. A short canvas particle burst celebrates the bin without adding anything to the Rocket core. Particle source ↗

Set shortcuts on the host

This sortable list keeps arrow keys and replaces Vim j/k with n/p. It stages reorders with Alt + those same keys. Render the attributes with the host; bindings are resolved when the component connects. The event is an intent: your page applies it and patches the confirmed HTML from its backend.

<section class="project-queue" aria-labelledby="queue-title">
  <h2 id="queue-title">Queue</h2>
  <rocket-sortable-list
    data-key-focus-next="ArrowDown n"
    data-key-focus-previous="ArrowUp p"
    data-key-move-down="Alt+ArrowDown Alt+n"
    data-key-move-up="Alt+ArrowUp Alt+p"
    data-on:rocket-sortable-move="
      $itemId = evt.detail?.['itemId'] ?? null;
      $before = evt.detail?.['before'] ?? null;
      @post('/queue/move')">
    <article class="queue-item" data-sortable-item="item-a" tabindex="0">First task</article>
    <article class="queue-item" data-sortable-item="item-b" tabindex="0">Next task</article>
  </rocket-sortable-list>
</section>

The rocket-sortable-move detail is { itemId, before }; an empty before appends. The example route and signals belong to the page, not the bundle. Set a shortcut attribute to an empty string to disable that intent; see the keyboard reference for the other surfaces and Kanban’s legacy aliases.

Style the states, not the internals

Scope styles under your component class. The host and items are ordinary light-DOM elements; preview and target attributes are styling hooks. By default the floating preview is a clone attached to the document body, so an item class lets it keep your theme outside the host. Give pointer items touch-action: none and a visible keyboard focus state:

.project-queue, .queue-item[data-drag-preview] {
  --queue-accent: var(--color-accent, #256c62);
  --queue-surface: var(--color-surface, #fff);
}
.project-queue rocket-sortable-list {
  display: grid;
  gap: .5rem;
  position: relative;
}
:is(.project-queue [data-sortable-item], .queue-item[data-drag-preview]) {
  position: relative;
  padding: .75rem 1rem;
  border: 1px solid var(--queue-accent);
  border-radius: var(--radius-card, .5rem);
  background: var(--queue-surface);
  cursor: grab;
  touch-action: none;
}
.project-queue [data-sortable-item]:focus-visible {
  outline: 2px solid var(--queue-accent);
  outline-offset: 2px;
}
.project-queue [data-dragging] { opacity: .45; }
.queue-item[data-drag-preview] { box-shadow: 0 12px 24px #0003; }
.project-queue [data-drop-before]::before,
.project-queue rocket-sortable-list[data-drop-end]::after {
  content: "";
  position: absolute;
  left: 0;
  right: 0;
  height: 3px;
  background: var(--queue-accent);
  pointer-events: none;
}
.project-queue [data-drop-before]::before { top: -5px; }
.project-queue rocket-sortable-list[data-drop-end]::after { bottom: -5px; }

Replace the preview or target markup

For richer affordances, render inert <template> fragments with your items and host. A direct-child data-rocket-preview template on an item replaces that item’s floating clone; its class is copied onto the preview wrapper, which moves under document.body. Its size is yours to style; --rocket-source-width and --rocket-source-heightexpose the original dimensions if useful. Direct-child data-rocket-target templates on the host supply target decorations. Rocket inserts their content into a noninteractive [data-rocket-target-indicator] wrapper at the active target for both pointer and keyboard staging. Give target items and containers position: relative so you can position the indicator inside them:

<!-- Inside a server-rendered [data-sortable-item] -->
<template data-rocket-preview class="queue-preview">
  <strong>Moving: First task</strong>
</template>

<!-- Direct children of the rocket-sortable-list host -->
<template data-rocket-target="before">
  <span class="queue-target">Place above</span>
</template>
<template data-rocket-target="end">
  <span class="queue-target">Place at end</span>
</template>

.queue-preview[data-drag-preview] {
  display: grid;
  place-items: center;
  width: max-content;
  min-height: var(--rocket-source-height);
  border: 2px solid var(--color-accent, #256c62);
  border-radius: var(--radius-card, .5rem);
  background: var(--color-surface, #fff);
}
.project-queue [data-rocket-target-indicator] {
  left: 0;
  right: 0;
  color: var(--queue-accent);
}
.project-queue [data-rocket-target-indicator="before"] { top: -1.5rem; }
.project-queue [data-rocket-target-indicator="end"] { bottom: -1.5rem; }
.project-queue .queue-target { display: block; }

Without a preview template Rocket clones the source item. Without a target template the existing data-drop-* states remain available for CSS-only markers like those above. When using a template indicator, replace those pseudo-element marker rules with your indicator styles. Other target kinds are into for tree folders and cell for bento grids; a bare data-rocket-target template can serve every kind on a host. Geometry and the semantic move event still belong to the surface.

Match the affordance to the layout

All surfaces expose [data-dragging] on the source, [data-drag-preview] on the detached clone, and [data-key-staging] on the host during keyboard moves. Bento also needs data-columns to match its CSS grid tracks, a fixed grid-auto-rows, and tile grid-column/grid-row styles that match their rendered position data. See the example CSS ↗ for complete layout and state rules.

STEP 09 / CONTEXTUAL ACTIONS

A menu at the point of intent

Right-click a row or use its Actions button. The server renders one inert template; Rocket clones it on demand, binds the row’s contextId, handles focus and nested menus, and emits a semantic action. The page decides what that action means and returns a small SSE patch. No menu fetch is needed for these shared, non-sensitive actions.

<article data-context-id="record-a" data-menu-for="record-menu">
  <button data-menu-for="record-menu" aria-haspopup="menu">Actions</button>
</article>
<rocket-context-menu id="record-menu" data-on:rocket-menu-action="$menu = evt.detail; @post('/menu-action')">
  <template data-rocket-menu>
    <button role="menuitem" data-action="inspect">Inspect {contextId}</button>
    <button role="menuitem" data-submenu="more" aria-haspopup="menu">More →</button>
    <div id="more" role="menu" popover="auto">
      <button role="menuitem" data-action="archive">Archive</button>
    </div>
  </template>
</rocket-context-menu>

rocket-menu-action → { action, contextId }

Menus may nest as deeply as your markup needs. Opening focuses the menu; Down starts at the first item (Up starts at the last). Arrow keys or h/j/k/l move through a level, Right opens a submenu, and Left, Backspace or Escape returns one level. Escape at the root closes the menu; Enter or Space on the menu activates its first item. Home/End and per-host data-key-* overrides also work. On macOS,Ctrl+n / Ctrl+p also move next / previous, following familiar Control-key text navigation; Command-key browser shortcuts remain untouched. On other platforms the Control pair can be opted into with data-key-focus-next="ArrowDown j Ctrl+n" and data-key-focus-previous="ArrowUp k Ctrl+p". Native popovers provide the top layer and light dismiss; CSS anchors position the menu and flip nested panels at viewport edges, with measured coordinates as a fallback. Your CSS owns the presentation. Context placeholders bind in text, data-menu-param-*, aria-label, and title attributes; executable directives are left as server-rendered.

For fresh options, fetch page-owned HTML before opening and morph the template, or render a direct child marked data-rocket-menu-content for live server markup. Then call menu.openFor(trigger). Live markup stays in the host after close; use menu.closeMenu(refocus?) and menu.isOpen() when coordinating a page-owned menu lifecycle. rocket-menu-scope emits { root, active } when its keyboard scope opens or closes. Additional non-sensitive values can be passed as menu.openFor(trigger, undefined, { label: "Example" }) and used as {label} in the template. The Rocket never fetches menus or makes authorization decisions. See menu behavior ↗ and JSX adapter ↗.

INTERACTION / INLINE EDIT

Edit a title in place

Double-click the title, change it, then press Enter or leave the field. Escape cancels. The Rocket recognizes the two title presses even when a parent captures the pointer; it emits request, commit and cancel events. The page owns edit mode, input state and saving.

<rocket-inline-edit data-context-id="card-a">
  <span data-inline-edit-trigger data-inline-edit-value>Title from server</span>
  <input data-inline-edit-input aria-label="Edit title" value="Title from server">
</rocket-inline-edit>

rocket-inline-edit-request → { contextId }
rocket-inline-edit-commit → { contextId, value }
rocket-inline-edit-cancel → { contextId }

The element leaves classes and layout to your CSS; it never submits a request or stores a second copy of the title. See editor behavior ↗ and JSX adapter ↗.

SERVER EXAMPLES / 04

Contractual obligations

The Hono JSX adapter packages the required markup and event binding into a component; this guide uses it to send moves to its in-browser fixture. The Go example writes the same DOM withhtml/template and handles moves on the server. Your page chooses the Datastar action that receives each event.

Hono JSX

const move = {
  event: "rocket-kanban-move",
  attrs: {
    "data-on:rocket-kanban-move":
      "$cardId = evt.detail?.['cardId'] ?? null; " +
      "$col = evt.detail?.['col'] ?? null; " +
      "$before = evt.detail?.['before'] ?? null; @post('/move')",
  },
};

<KanbanBoard id="kanban-board" columns={columns} move={move} />

View the JSX adapter source ↗

Go template

<rocket-kanban-board id="kanban-board"
   data-on:rocket-kanban-move="$cardId = evt.detail?.['cardId'] ?? null;
     $col = evt.detail?.['col'] ?? null;
     $before = evt.detail?.['before'] ?? null; @post('/move')">
  {{range .Columns}}
    <section data-kanban-lane="" data-col="{{.ID}}">
      <div data-kanban-lane-cards="">
        {{range .Cards}}
          <article data-kanban-card="{{.ID}}" tabindex="0">{{.Title}}</article>
        {{end}}
      </div>
    </section>
  {{end}}
</rocket-kanban-board>

View the Go server source ↗