3. Drag and drop

Dragging a card is the first thing in this series that HTMX can’t do well. A drag has state that lives in the browser for as long as your finger is down, and round-tripping to the server on every pointer move would feel awful. So this is where islands earn their place. You’ll add position columns to the models, mount a small JavaScript component over the board, and let it update the UI immediately while the save happens behind it. You’ll use: OrderingMixin, __ordering_scope__, islands, the built-in draggable config, this.optimistic(), and an API route returning JSON.

Prerequisites

Continue from part 2
Start fresh

Your app needs the SQLite database, the Column and Card models, the HTMX routes and the two partials. Nothing else to do.

feather new kanban

Accept simple, choose sqlite, then copy the part 2 code from the Starting Point section of the source tutorial.

Step 1: Add OrderingMixin

OrderingMixin adds a position column and the methods to shuffle it.

models/column.py

"""Column model for Kanban board."""

from feather.db import db, Model
from feather.db.mixins import UUIDMixin, TimestampMixin, OrderingMixin


class Column(UUIDMixin, TimestampMixin, OrderingMixin, Model):
    """Kanban column with position-based ordering."""

    __tablename__ = "columns"

    title = db.Column(db.String(100), nullable=False)
    cards = db.relationship(
        "Card",
        backref="column",
        cascade="all, delete-orphan",
        order_by="Card.position"  # changed from created_at
    )

    def __repr__(self):
        return f"<Column {self.title}>"

models/card.py

"""Card model for Kanban board."""

from feather.db import db, Model
from feather.db.mixins import UUIDMixin, TimestampMixin, OrderingMixin


class Card(UUIDMixin, TimestampMixin, OrderingMixin, Model):
    """Kanban card with position scoped per column."""

    __tablename__ = "cards"
    __ordering_scope__ = ["column_id"]  # position is unique per column

    title = db.Column(db.String(200), nullable=False)
    description = db.Column(db.Text)
    column_id = db.Column(
        db.String(36),
        db.ForeignKey("columns.id"),
        nullable=False
    )

    def __repr__(self):
        return f"<Card {self.title}>"

Method	What it does
`position`	The integer column the mixin adds
`insert_at_end()`	Sets position to the current max plus one
`move_to(n)`	Moves to position n, shifting everything else
`query_ordered()`	Queries sorted by position
`reorder_all()`	Closes gaps after a delete
`get_max_position()`	Returns the highest position

__ordering_scope__ is the line that matters. Without it, positions would be unique across the whole table, and cards in different columns would fight over them. With it, each column’s cards start again at zero.

Step 2: The migration

feather db migrate -m "Add position to columns and cards"
feather db upgrade

Step 3: Update the services

services/column_service.py

"""ColumnService - Business logic for columns."""

from feather import Service
from feather.exceptions import NotFoundError
from models import Column


class ColumnService(Service):
    """Column service."""

    def list_all(self) -> list[Column]:
        """List all columns in order."""
        return Column.query_ordered().all()

    def get_by_id(self, id: str) -> Column:
        """Get column by ID or raise NotFoundError."""
        column = Column.query.get(id)
        if not column:
            raise NotFoundError("Column", id)
        return column

    def create(self, title: str) -> Column:
        """Create a new column at the end."""
        column = Column(title=title)
        column.insert_at_end()
        self.save(column)
        return column

    def delete(self, id: str) -> None:
        """Delete a column and its cards."""
        column = self.get_by_id(id)
        self.db.delete(column)
        self.db.commit()
        # close the gap left behind
        Column.reorder_all()
        self.db.commit()

services/card_service.py

"""CardService - Business logic for cards."""

from feather import Service
from feather.exceptions import NotFoundError
from models import Card


class CardService(Service):
    """Card service."""

    def get_by_id(self, id: str) -> Card:
        """Get card by ID or raise NotFoundError."""
        card = Card.query.get(id)
        if not card:
            raise NotFoundError("Card", id)
        return card

    def create(self, column_id: str, title: str) -> Card:
        """Create a new card at the end of a column."""
        card = Card(column_id=column_id, title=title)
        card.insert_at_end()
        self.save(card)
        return card

    def delete(self, id: str) -> None:
        """Delete a card and reorder the rest."""
        card = self.get_by_id(id)
        column_id = card.column_id
        self.db.delete(card)
        self.db.commit()
        Card.reorder_all(column_id=column_id)
        self.db.commit()

    def move(self, card_id: str, to_column_id: str, to_position: int) -> Card:
        """Move a card, possibly into a different column."""
        card = self.get_by_id(card_id)
        old_column_id = card.column_id

        if to_column_id != old_column_id:
            # move it across, parked at the end for now
            card.column_id = to_column_id
            max_pos = Card.get_max_position(column_id=to_column_id)
            card.position = max_pos + 1
            self.db.commit()

            # close the gap in the column it left
            Card.reorder_all(column_id=old_column_id)
            self.db.commit()

        card.move_to(to_position)
        self.db.commit()

        return card

move() handles the awkward case. A card crossing between columns has to leave one ordering scope and join another, so it moves across first, parks at the end, and only then slots into position.

Step 4: The move API route

routes/api/board.py

"""API routes for Kanban board."""

from flask import request
from feather import api
from feather.services import inject
from services import CardService


@api.post("/cards/move")
@inject(CardService)
def move_card(card_service: CardService):
    """Move a card to a new position."""
    data = request.get_json()
    card = card_service.move(
        card_id=data["cardId"],
        to_column_id=data["toColumnId"],
        to_position=data["toPosition"]
    )
    return {
        "success": True,
        "card": {"id": card.id, "position": card.position}
    }

This is the first API route in the series, and the distinction is worth stating plainly. HTMX routes return HTML because the browser is going to insert it. This route returns JSON because the island already moved the element and only needs to report where it landed.

Step 5: The island

static/islands/kanban-board.js

/**
 * Kanban Board Island
 *
 * Handles drag-and-drop of cards between columns with optimistic updates.
 */
island("kanban-board", {
  draggable: {
    items: ".kanban-card",           // what can be dragged
    zones: ".column-cards",          // where it can be dropped
    handle: ".drag-handle",          // restrict dragging to this element

    onDrop(item, zone, info, e) {
      // the DOM has already moved; now make it stick

      this.optimistic(
        // nothing extra to do optimistically, the drag system moved it
        () => {},
        // persist
        () => this.api.post("/api/cards/move", {
          cardId: info.itemId,
          toColumnId: info.toZoneId,
          toPosition: info.toIndex
        })
      ).catch(err => {
        console.error("Failed to move card:", err);
        window.location.reload();
      });
    }
  }
});

Config	Meaning
`items`	Selector for draggable elements
`zones`	Selector for drop targets
`handle`	Optional, restricts the grab area
`onDrop`	Runs after the drop, with `info` carrying `itemId`, `fromIndex`, `toIndex`, `fromZoneId` and `toZoneId`
`this.optimistic()`	Applies the change now, rolls back if the call fails
`this.api`	The CSRF-aware helper, so you never call `fetch` directly

Step 6: Add the drag handle

templates/partials/card.html

{#
Card Partial
============
Renders a single Kanban card (draggable).
#}
{% from "components/icon.html" import icon %}

<div id="card-{{ card.id }}"
     class="kanban-card"
     data-id="{{ card.id }}">
    <div class="card-content">
        <span class="drag-handle">
            {{ icon("drag_indicator", size="sm") }}
        </span>
        <p class="card-title">{{ card.title }}</p>
        <button hx-delete="/htmx/cards/{{ card.id }}"
                hx-target="#card-{{ card.id }}"
                hx-swap="outerHTML"
                hx-confirm="Delete this card?"
                class="btn-icon-subtle">
            {{ icon("close", size="sm") }}
        </button>
    </div>
</div>

Two changes: data-id so the island can identify the card, and the handle itself.

Step 7: Make the column a drop zone

templates/partials/column.html

{#
Column Partial
==============
Renders a single Kanban column with its cards.
#}
{% from "components/icon.html" import icon %}

<div id="column-{{ column.id }}" class="kanban-column">
    <div class="column-header">
        <h2 class="column-title">{{ column.title }}</h2>
        <button hx-delete="/htmx/columns/{{ column.id }}"
                hx-target="#column-{{ column.id }}"
                hx-swap="outerHTML"
                hx-confirm="Delete this column and all its cards?"
                class="btn-icon-danger">
            {{ icon("close", size="sm") }}
        </button>
    </div>

    <!-- Cards container (drop zone) - needs data-id for Islands -->
    <div id="column-{{ column.id }}-cards"
         class="column-cards"
         data-id="{{ column.id }}">
        {% for card in column.cards %}
            {% include "partials/card.html" %}
        {% else %}
            <p class="empty-column empty-placeholder">No cards yet</p>
        {% endfor %}
    </div>

    <form hx-post="/htmx/columns/{{ column.id }}/cards"
          hx-target="#column-{{ column.id }}-cards"
          hx-swap="beforeend"
          hx-on::after-request="if(event.detail.successful) { this.reset(); this.closest('.kanban-column').querySelector('.empty-placeholder')?.remove(); }"
          class="column-footer">
        <input type="text"
               name="title"
               placeholder="Add a card..."
               class="input-card-title">
    </form>
</div>

The data-id on .column-cards is what makes it a drop zone. The empty-placeholder class exists so the “No cards yet” line disappears when a card arrives.

Step 8: Mount the island

templates/pages/board.html

{% extends "base.html" %}
{% from "components/icon.html" import icon %}

{% block title %}Kanban Board{% endblock %}

{% block content %}
<div class="kanban-container">
    <header class="kanban-header">
        <h1 class="kanban-title">
            {{ icon("view_kanban", size="lg") }} Kanban Board
        </h1>
        <div class="kanban-header-right">
            <button id="add-column-btn" class="btn-primary">
                {{ icon("add", size="sm") }} Add Column
            </button>
            <button data-toggle-dark-mode class="dark-mode-toggle" title="Toggle dark mode">
                <span class="material-symbols-outlined icon-light">bedtime</span>
                <span class="material-symbols-outlined icon-dark">sunny</span>
            </button>
        </div>
    </header>

    <!-- data-island mounts the kanban-board island here -->
    <div data-island="kanban-board" class="kanban-board-wrapper">
        <div id="kanban-board" class="kanban-board">
            {% for column in columns %}
                {% include "partials/column.html" %}
            {% endfor %}
        </div>
    </div>
</div>
{% endblock %}

{% block scripts %}
{% if config.DEBUG %}
<script type="module" src="http://localhost:5173/static/js/board.js"></script>
{% else %}
<script src="{{ url_for('static', filename='js/board.js') }}"></script>
{% endif %}
{% endblock %}

{% block islands %}
{% if config.DEBUG %}
<script type="module" src="http://localhost:5173/static/islands/kanban-board.js"></script>
{% else %}
<script src="{{ feather_asset('islands/kanban-board') }}"></script>
{% endif %}
{% endblock %}

Islands load from the Vite dev server in debug, for hot reload, and through feather_asset() in production, which resolves the content-hashed build output. That’s why islands get their own block rather than sitting in scripts.

Step 9: The drag CSS

static/css/app.css

    /* Drag handle */
    .drag-handle {
        @apply text-gray-300 dark:text-gray-600
               hover:text-gray-500 dark:hover:text-gray-400 cursor-grab;
    }

    /* Dragging state (added by Islands) */
    .kanban-card.dragging {
        @apply opacity-50 shadow-lg;
    }

    /* Drop zone hover state (added by Islands) */
    .column-cards.drag-over {
        @apply bg-gray-300 dark:bg-gray-700 ring-1 ring-indigo-400 ring-inset;
    }

    /* Drop placeholder (added by Islands) */
    .feather-drop-placeholder {
        @apply h-0.5 bg-indigo-400 rounded my-1;
    }

    /* Board wrapper for island */
    .kanban-board-wrapper {
        @apply overflow-x-auto;
    }

The islands runtime adds three classes for you: .dragging on the element in flight, .drag-over on the zone under the pointer, and .feather-drop-placeholder on the marker showing where it will land. The scaffolded app.css has base styles for all three, and these are the Kanban-specific overrides. Add them inside the existing @layer components block.

Step 10: Test it

feather dev

Grab a card by its six-dot handle and drag it.
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 round trip.
Refresh. The positions held.

Prompt Claude

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.

Implement Build Steps 1 through 9:
- OrderingMixin on both models, with __ordering_scope__ = ['column_id'] on Card
- The migration
- Ordered queries and a move() method on CardService that handles moving between
  columns, not just within one
- The move API route under routes/api/
- The kanban-board island using the built-in draggable config
- data-id attributes and a drag handle on the partials, data-id on the drop zone
- The island mount and the islands block on the board template
- Drag-drop CSS

Two conventions matter here. Use this.api from the island rather than raw fetch, so
CSRF is handled. 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.

feather check has two rules aimed at exactly this part. missing-island catches a template mounting an island that doesn’t exist, and orphan-island catches an island nothing mounts. Both are easy to trip while wiring this up.

Checkpoint

Columns and cards have stable positions
A card can be dragged within a column and between columns
The dragged card dims, and a placeholder shows where it will land
The card lands instantly rather than after a round trip
Positions survive a refresh
feather check passes

Files you created or changed

models/
├── column.py               # OrderingMixin
└── card.py                 # OrderingMixin + scope

services/
├── column_service.py       # ordered queries
└── card_service.py         # move()

routes/
└── api/board.py            # new

templates/
├── pages/board.html        # island mount
└── partials/
    ├── column.html         # data-id drop zone
    └── card.html           # data-id + drag handle

static/
├── css/app.css             # drag styles
└── islands/
    └── kanban-board.js     # new

migrations/                 # generated

What you learned

OrderingMixin and the methods it adds
__ordering_scope__ for positions relative to a parent
Declaring and mounting an island
The built-in draggable config
this.optimistic() and rollback on failure
API routes that return JSON rather than HTML
How islands load differently in debug and production

Next: add real users

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

​Prerequisites

​Step 1: Add OrderingMixin

​Step 2: The migration

​Step 3: Update the services

​Step 4: The move API route

​Step 5: The island

​Step 6: Add the drag handle

​Step 7: Make the column a drop zone

​Step 8: Mount the island

​Step 9: The drag CSS

​Step 10: Test it

​Prompt Claude

​Checkpoint

​What you learned

Next: add real users

Prerequisites

Step 1: Add OrderingMixin

Step 2: The migration

Step 3: Update the services

Step 4: The move API route

Step 5: The island

Step 6: Add the drag handle

Step 7: Make the column a drop zone

Step 8: Mount the island

Step 9: The drag CSS

Step 10: Test it

Prompt Claude

Checkpoint

What you learned