Skip to content
Tutorials Center
My learning

Topics

Lesson 21 of 28 ยท Projects

Project: Todo List with HTMX and Alpine

Build a todo list where the server owns the data: add, toggle and delete with HTMX, edit in place and filter with Alpine.js, and update counts out of band.

A todo list is the classic first project because it touches every basic skill: creating, reading, updating and deleting data, and a bit of interface state on top. In this project you will build one where the roles are clear. The server owns the todos and the count of open items. HTMX sends every change and swaps in the HTML the server returns. Alpine.js handles what only the browser needs to know: which item is being edited, and which filter tab is selected.

You will build it in two steps: first the core with a server, then the finished app. If any attribute looks unfamiliar, the earlier lessons explain it: Targets and Swap Strategies covers hx-swap-oob, and Using HTMX and Alpine.js Together covers scopes inside swapped content.

The plan

Server Keeps the todos and counts what is left.
HTMX Sends add, toggle, rename and delete.
Alpine Edit mode and the All / Open / Done filter.
1 / 2

The server routes

The mock server plays the role of your backend. Every route returns HTML, and a small function item() renders one todo, so adding, toggling and renaming all reuse it. This is exactly how you would write it with a template partial.

Action Request Response
List GET /todos all items plus the count
Add POST /todos the new item plus the count
Toggle PATCH /todos/toggle the changed item plus the count
Rename PUT /todos/rename the changed item
Delete DELETE /todos/remove only the count (the item disappears)

The "plus the count" part uses an out-of-band swap. Any element in the response with hx-swap-oob="true" replaces the element on the page that has the same id, no matter where the main swap goes.

Step 1: add and list

Start with the smallest working piece: a form that adds a todo and a list that loads when the page opens.

Todo core: list and add

Add a few todos. Each response carries the new <li> for the list and a fresh <span id="count"> that HTMX routes to the header. The form clears itself through an Alpine listener on htmx:after-request (the bare x-data just turns Alpine on for that element). Server-side validation matters too: the handler trims the text and rejects empty input with a 422, so a request that skips the browser's required check is still handled.

Step 2: toggle, edit, delete and filter

Now the full app. Each item becomes a small component with its own edit state, while the outer wrapper holds the filter.

Three things deserve attention:

  • Scopes. The wrapper has x-data="{ filter: 'all' }". Items arrive later from the server, but they sit inside the wrapper, so their expressions can read filter. Each item adds its own x-data="{ editing: false }", and nested scopes merge.
  • Filtering without the server. Every item carries data-done="1" or "0", and x-show compares it with the filter. The server does not need to know which tab is open.
  • Replacing items. Toggle and rename swap the item with outerHTML, so the new HTML comes from the same item() function. A replaced item starts with editing: false, which is exactly what you want after saving.
Todo list: complete app

Try the whole loop: tick a todo (the item and the count update in one response), switch to Done (instant, no request), double-click a title to edit it, press Enter to save, and delete an item. Deleting works because an empty outerHTML swap removes the target, while the leftover <span id="count"> is processed out of band.

What the Alpine parts do

  • @dblclick="editing = true; $nextTick(() => $refs.edit.select())" shows the input, then waits one tick so the input is visible before selecting its text.
  • x-show="editing" on the form together with x-cloak keeps it hidden from the first paint.
  • The form has no submit button: pressing Enter submits it, and HTMX sends it as PUT because of hx-put.

On a real server, the rename route would also check that the todo belongs to the signed-in user. See Server-Side Setup for the checklist.

Ideas to extend it

  1. Add a "Clear completed" button with hx-delete. It could return the whole list, swapped into #list with innerHTML.
  2. Make the checkbox optimistic with Alpine, then let the server response confirm it.
  3. Return a 409 when two tabs edit the same todo, and display the conflict using htmx:responseError.
  4. Replace the in-memory array with a database table. The HTML and attributes stay unchanged.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why does the server response for a toggle contain a <span id="count" hx-swap-oob="true">?

    An element with hx-swap-oob replaces the page element with the same id, independent of the main target, so one response can update two places.
  2. 2. Where should the active filter (All, Open, Done) live in this app?

    The filter only changes which already-loaded items are shown, so Alpine can handle it instantly without a request.
  3. 3. Why can items loaded by HTMX read the filter variable from the wrapper's x-data?

    The swapped items are inside the wrapper element, so Alpine initializes them as children of that component and their scope includes the parent's data.
  4. 4. What happens when a delete response has an empty body except for an out-of-band element, with hx-swap="outerHTML" on the item?

    outerHTML replaces the target with the (empty) main content, which removes it. The out-of-band span is handled separately.

Summary

  • The server owns todos and counts; each response returns ready-made HTML from one item() partial.
  • HTMX verbs map to actions: POST adds, PATCH toggles, PUT renames, DELETE removes.
  • hx-swap-oob lets one response update the list item and the header count.
  • Alpine handles edit mode and the filter, and swapped items can read the wrapper's scope.
  • Validate on the server too, even when the form has required.

Next project: Live Search and Filterable Table.