Todo list¶
Add, edit, complete, filter and delete tasks, saved to a JSON file.
Same example in PowerShell: Todo list

Real capture on KDE Plasma 6.6 Wayland with the released packages.
What it teaches: form submit; delegated list events; escaping user text; keyboard editing; atomic JSON persistence.
Run it¶
uv init --app myapp && cd myapp # once: a uv project for your app
uv add nativehtmlkit
# save the example file(s) in the project folder, then:
uv run todo.py
Related guide: events and callbacks
Source: todo.py¶
"""Todo list: add, edit, complete and delete tasks, saved to a JSON file.
What it teaches
* form ``submit`` events (the Add button, or Enter in the text field, submits the form)
* one delegated handler for a whole list (``element="todos"`` matches every child)
* escaping user text with ``html.escape`` before ``replace_html``
* keyboard handling (Escape cancels an edit) and in-place editing
* persistence: an atomic JSON write into the per-application data directory
This is the finished app of the tutorial in docs/tutorials/todo-app.md.
Run: uv run todo.py
Data: <per-user data directory>/todos.json (printed at start-up).
"""
from __future__ import annotations
import html
import json
import os
from pathlib import Path
from nativehtmlkit import Application, Window
APP_ID = "org.nativehtmlkit.examples.todo"
PAGE = """<!doctype html>
<html><head><meta charset="utf-8"><style>
:root { --bg:#f6f7fb; --card:#fff; --text:#1d2433; --muted:#6b7385; --accent:#3a6ff7; --line:#e3e6ee; }
@media (prefers-color-scheme: dark) {
:root { --bg:#141923; --card:#1d2433; --text:#e8ecf5; --muted:#9aa3b5; --accent:#7aa2ff; --line:#2d3546; }
}
body { margin:0; background:var(--bg); color:var(--text); font:15px/1.4 sans-serif; }
main { max-width:560px; margin:32px auto; padding:0 20px; }
h1 { font-size:28px; margin:0 0 16px; }
form { display:flex; gap:8px; }
input[type=text] { flex:1; padding:9px 10px; border:1px solid var(--line); border-radius:6px;
background:var(--card); color:var(--text); }
button { padding:8px 12px; border:0; border-radius:6px; background:var(--accent); color:#fff; cursor:pointer; }
button.plain { background:transparent; color:var(--muted); padding:4px 8px; }
ul { list-style:none; padding:0; margin:16px 0; background:var(--card); border-radius:8px; }
li { display:flex; align-items:center; gap:10px; padding:10px 12px; border-bottom:1px solid var(--line); }
li:last-child { border-bottom:0; }
li .text { flex:1; }
li.done .text { text-decoration:line-through; color:var(--muted); }
li form { flex:1; }
.empty { color:var(--muted); padding:16px 12px; }
footer { display:flex; justify-content:space-between; align-items:center; color:var(--muted); }
nav button { background:transparent; color:var(--muted); }
nav button.active { color:var(--accent); font-weight:bold; }
</style></head>
<body><main>
<h1>Todo</h1>
<form id="new-form">
<input id="new-title" type="text" placeholder="What needs doing?" required maxlength="200">
<button id="add" type="submit">Add</button>
</form>
<ul id="todos"></ul>
<footer>
<span id="count">0 items left</span>
<nav id="filters">
<button id="filter-all" class="active">All</button>
<button id="filter-active">Active</button>
<button id="filter-done">Completed</button>
</nav>
<button id="clear-done" class="plain">Clear completed</button>
</footer>
</main></body></html>"""
FILTERS = {"all": lambda item: True, "active": lambda item: not item["done"], "done": lambda item: item["done"]}
def load_todos(path: Path) -> list[dict]:
"""Read saved todos; a missing or unreadable file starts an empty list."""
try:
data = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError):
return []
return [{"id": int(x["id"]), "title": str(x["title"]), "done": bool(x["done"])}
for x in data if isinstance(x, dict) and {"id", "title", "done"} <= x.keys()]
def save_todos(path: Path, todos: list[dict]) -> None:
"""Write atomically: a crash mid-write never leaves a truncated file."""
path.parent.mkdir(parents=True, exist_ok=True)
temporary = path.with_name(path.name + ".tmp")
temporary.write_text(json.dumps(todos, indent=2, ensure_ascii=False), encoding="utf-8")
os.replace(temporary, path)
class TodoApp:
def __init__(self, window: Window, store: Path):
self.window, self.document, self.store = window, window.document, store
self.todos = load_todos(store)
self.next_id = max((t["id"] for t in self.todos), default=0) + 1
self.filter = "all"
self.editing: int | None = None
doc = self.document
doc.on("submit", self._on_submit) # new-form and the inline edit form
doc.on("change", self._on_change, element="todos") # checkboxes inside the list
doc.on("click", self._on_list_click, element="todos")
doc.on("keydown", self._on_key, element="todos")
doc.on("click", self._on_filter_click, element="filters")
doc.on("click", lambda _e: self.clear_done(), element="clear-done")
self.render()
# ----- actions (also called directly by the headless tests) -----
def add(self, title: str) -> None:
title = title.strip()
if title:
self.todos.append({"id": self.next_id, "title": title, "done": False})
self.next_id += 1
self.changed()
def toggle(self, todo_id: int, done: bool) -> None:
self._find(todo_id)["done"] = done
self.changed()
def rename(self, todo_id: int, title: str) -> None:
self.editing = None
if title.strip():
self._find(todo_id)["title"] = title.strip()
self.changed()
def delete(self, todo_id: int) -> None:
self.todos = [t for t in self.todos if t["id"] != todo_id]
self.changed()
def clear_done(self) -> None:
self.todos = [t for t in self.todos if not t["done"]]
self.changed()
def set_filter(self, name: str) -> None:
self.filter = name
for key in FILTERS:
(self.document.add_class if key == name else self.document.remove_class)(f"filter-{key}", "active")
self.render()
def start_edit(self, todo_id: int) -> None:
self.editing = todo_id
self.render()
self.document.focus("edit-title")
def changed(self) -> None:
save_todos(self.store, self.todos)
self.render()
# ----- rendering -----
def render(self) -> None:
visible = [t for t in self.todos if FILTERS[self.filter](t)]
rows = [self._row(t) for t in visible] or ['<li class="empty">Nothing here.</li>']
left = sum(not t["done"] for t in self.todos)
self.document.replace_html("todos", "".join(rows))
self.document.set_text("count", f"{left} item{'s' if left != 1 else ''} left")
def _row(self, todo: dict) -> str:
n, title = todo["id"], html.escape(todo["title"]) # user text is never trusted markup
if n == self.editing:
return (f'<li id="todo-{n}"><form id="edit-form-{n}">'
f'<input id="edit-title" type="text" value="{title}" maxlength="200"></form>'
f'<button id="todo-{n}-cancel" class="plain">Cancel</button></li>')
checked = " checked" if todo["done"] else ""
return (f'<li id="todo-{n}" class="{"done" if todo["done"] else ""}">'
f'<input id="todo-{n}-done" type="checkbox"{checked}>'
f'<span id="todo-{n}-text" class="text">{title}</span>'
f'<button id="todo-{n}-edit" class="plain">Edit</button>'
f'<button id="todo-{n}-delete" class="plain">Delete</button></li>')
# ----- event handlers -----
def _on_submit(self, event: dict) -> None:
if event["element"] == "new-form":
self.add(self.document.get_value("new-title"))
self.document.set_value("new-title", "")
elif event["element"].startswith("edit-form-"):
self.rename(int(event["element"].rsplit("-", 1)[1]), self.document.get_value("edit-title"))
def _on_change(self, event: dict) -> None:
todo_id, action = _parse(event["element"])
if action == "done":
self.toggle(todo_id, bool(event.get("checked")))
def _on_list_click(self, event: dict) -> None:
todo_id, action = _parse(event["element"])
if action == "edit":
self.start_edit(todo_id)
elif action == "delete":
self.delete(todo_id)
elif action == "cancel":
self.editing = None
self.render()
def _on_key(self, event: dict) -> None:
if event.get("key") == "Escape" and self.editing is not None:
self.editing = None
self.render()
def _on_filter_click(self, event: dict) -> None:
name = event["element"].removeprefix("filter-")
if name in FILTERS:
self.set_filter(name)
def _find(self, todo_id: int) -> dict:
return next(t for t in self.todos if t["id"] == todo_id)
def _parse(element: str) -> tuple[int | None, str | None]:
"""'todo-7-delete' -> (7, 'delete'); anything else -> (None, None)."""
parts = element.split("-")
if len(parts) == 3 and parts[0] == "todo" and parts[1].isdigit():
return int(parts[1]), parts[2]
return None, None
def build(app: Application, store: Path) -> TodoApp:
window = app.open_html(PAGE, title="Todo", width=640, height=620, min_width=420, min_height=360)
return TodoApp(window, store)
def main() -> None:
with Application.start(name="Todo", app_id=APP_ID) as app:
# desktop.paths is a public Core v1 method: per-application config/data/cache directories.
store = Path(app.rpc.call("desktop.paths")["data"]) / "todos.json"
print("Saving todos to", store)
build(app, store)
app.run()
if __name__ == "__main__":
main()