3. Drag and drop

A drag holds state in the browser for as long as the pointer is down, and reporting every pointer move to the server would make it feel slow. This is the case HTMX does not cover. An island handles it instead: a small piece of JavaScript mounted over the board, which moves the card immediately and persists the new position behind it.

What you’ll have

Columns and cards with stable positions
Cards you can drag within a column and between columns
Visual feedback while dragging, and a marker showing where the card will land
A card that moves instantly and rolls back if the server refuses

Which parts of Feather this uses

Islands

The draggable config and this.optimistic(), rather than hand-written pointer events.

OrderingMixin

A position column, and __ordering_scope__ to make it per-column.

API routes

The first route in the series that returns JSON rather than HTML.

feather check

Two rules here catch an island nothing mounts, or a mount with no island.

Step 1: Scaffold

Continue from part 2
Start fresh

Nothing to do. You need the SQLite database, the Column and Card models, the HTMX routes and the two partials, all of which part 2 produced.

feather new kanban

Accept simple, choose sqlite. The prompt below tells the assistant to rebuild part 2 first from the tutorial’s Starting Point section.

Step 2: Run the prompt

The prompt

I'm working through part 3 of the Feather Kanban tutorial series.

Read the tutorial first:
https://github.com/RolandFlyBoy/Feather/blob/main/tutorials/03-drag-and-drop.md

My app is the result of part 2: Column and Card models, services, HTMX
create and delete, and partials for column and card.

Build drag-and-drop from Build Steps 1 through 9:

- Add OrderingMixin to both models. Card needs __ordering_scope__ =
  ["column_id"] so positions run per column rather than across the whole
  table.
- A migration for the position columns.
- Update the services to query in position order, and add a move()
  method to CardService. It has to handle a card crossing between
  columns, not just reordering within one, and close the gap in the
  column it left.
- An API route under routes/api/ that takes the move as JSON.
- A kanban-board island using the built-in draggable config, with a drag
  handle.
- data-id on the cards and on the drop zones, and the island mount on
  the board template with its own islands block.
- The drag-drop CSS.

Two conventions matter here. Use this.api from inside the island rather
than raw fetch, so CSRF is handled for you. And use this.optimistic()
for the move, so the card lands immediately and rolls back if the server
rejects it.

Show me the migration before applying it. Then run `feather check` and
fix anything it reports, including orphan-island or missing-island.

Then explain two things: why Card needs an ordering scope and Column
doesn't, and what happens in the UI if the API call fails.

Step 3: Test it

feather dev

Grab a card by its handle and drag it. The card should dim while it moves.
Drop it above or below another card in the same column.
Drag one into a different column.
Watch it land immediately rather than after a pause.
Refresh. The positions held.

Then test the failure path, which is the part most implementations get wrong:

# stop the server while the browser is still open, then drag a card

The card should snap back where it came from rather than sitting in a position the database doesn’t know about.

feather check

What the framework did

Ordering comes from a mixin. OrderingMixin brought position, move_to(), insert_at_end() and reorder_all(). The service calls them; nothing recalculates indexes by hand. See Models. __ordering_scope__ is the line that matters. Without it, positions would be unique across the whole cards table and two columns would fight over them. With it, each column’s cards start again at zero. The island didn’t call fetch. this.api is the CSRF-aware helper, and raw fetch is a feather check error, because a POST without the token fails in production and works in nobody’s test. See Islands. Rollback is handled for you. this.optimistic() takes the instant change and the server call, and rolls the first back if the second fails. That’s the rollback you tested above. The route returned JSON. Every other route so far returned HTML because the browser was going to insert it. Here the island already moved the element and only needs to report where it landed, so routes/api/ is the right home. See Routes.

Next: add real users

Google sign-in, roles, an admin panel, file attachments and PDF export.

Get started

Tutorial: build a Kanban app

Building the UI

Backend

Features

Tooling

Testing

Deployment

3. Drag and drop

What you’ll have

Which parts of Feather this uses

Islands

OrderingMixin

API routes

feather check

Step 1: Scaffold

Step 2: Run the prompt

Step 3: Test it

What the framework did

Next: add real users

​What you’ll have

​Which parts of Feather this uses

Islands

OrderingMixin

API routes

feather check

​Step 1: Scaffold

​Step 2: Run the prompt

​Step 3: Test it

​What the framework did

Next: add real users

What you’ll have

Which parts of Feather this uses

Step 1: Scaffold

Step 2: Run the prompt

Step 3: Test it

What the framework did