Abstract:

This article by Loren Stewart, titled "Bookmarkable by Design: URL-Driven State in HTMX," advocates for a simplified state management pattern in HTMX applications by using URL query parameters as the single source of truth. The author outlines a three-step process: the server reads URL parameters to render the initial view, HTML forms with hidden fields are used to coordinate and preserve state across requests, and HTMX's hx-push-url attribute automatically synchronizes the state back to the browser's URL. This approach creates inherently bookmarkable, shareable, and SEO-friendly interfaces without the complexity of client-side state management libraries. The accompanying Hacker News discussion largely praises this return to web fundamentals but also introduces critical nuances, debating the true bookmarkability of pagination, the oversimplification of "single source of truth" in complex applications, and the general lack of robust URL state management in modern frameworks.

Leveraging the URL for State Management in HTMX: Key Concepts and Community Discussion

• Core Principle: URL as the Single Source of Truth: The article proposes using URL query parameters (/?status=active&sort=price) to manage application state for features like filtering, sorting, and pagination. This eliminates the need for complex JavaScript state management libraries.
• The 3-Step Implementation Pattern:
  1. Server Reads State: The backend endpoint reads parameters from the URL to query data and render the correct initial view.
  2. Forms Coordinate State: HTML forms, combined with hidden input fields, are used to hold the current state. HTMX attributes like hx-include and hx-vals ensure this state is preserved and sent with subsequent requests.
  3. Automatic URL Syncing: The hx-push-url="true" attribute tells HTMX to automatically update the browser's URL with the parameters from the request, which also ensures the browser's back/forward buttons work correctly.
• Key Benefits of the Pattern: This approach provides a transparent debugging experience (the state is visible in the URL), creates shareable and bookmarkable links by default, and improves SEO since every application state is a crawlable URL.
• Discussion Point - The Limits of Bookmarkable Pagination: The Hacker News discussion critiques that using page numbers (e.g., page=2) is not truly bookmarkable, as the data on that page can change over time. Commenters suggest cursor-based pagination (e.g., start_after=item_id) as a more robust solution, though its UX for all cases is also debated.
• Discussion Point - State is More Complex Than a Single Source: A prominent counter-argument highlights that real-world applications often have multiple levels of state: "in-progress" (unedited form inputs), "committed" (the state sent to the server), and "loaded" (the state returned from the server). The article's simple pattern may not cover these complex, asynchronous edge cases.
• Discussion Point - A Rediscovered Classic Pattern: Many commenters note that this URL-driven approach is not new but a fundamental pattern from the pre-SPA web of the 1990s. They credit HTMX for re-popularizing this simple and powerful technique.
• Discussion Point - Framework and Tooling Support: A sub-thread laments the poor support for managing URL search parameters in many modern frameworks. Libraries like nuqs (for React/Next.js) and Tanstack Router are mentioned as valuable tools that provide first-class, typed support for URL state.
• Discussion Point - Updating Other UI Elements: When an HTMX swap updates a piece of the page, other elements (like toast notifications or links in a sidebar) may also need to be updated. The discussion identifies hx-swap-oob (out-of-band swaps) as the idiomatic HTMX solution for this use case.