Documentation

Welcome to the django-htmx-nav documentation.

This library provides lightweight primitives to synchronize multi-region navigation chrome (sidebars, breadcrumbs, badges, tabs) during HTMX requests while keeping the URL as the single source of truth.

---

Documentation Roadmap

• Getting Started: 3-minute tutorial to get your first partial view and out-of-band swap working.

• Topic Guides:

  • Dynamic Targeting & Nested Navigation: Coordinate nested tabs, subtabs, and conditional swaps using the unified Target condition vocabulary.

  • Application Shells & Class-Based Views: Eliminate repetitive boilerplate across 20+ views with make_shell_renderer and make_shell_view_mixin.

  • Out-of-Band Swaps Deep Dive: Learn how to use unwrapped templates, fast text updates (Swap.text), element deletion (Swap.delete), and flash messages (has_messages).

• Operations & Testing:

  • Visual Swap Debugging: Highlight DOM elements with visual animations as they swap during development.

  • Testing: Write robust unit tests for your swaps and renderers with Django’s test client.

• Architecture & Reference:

  • Settings: Configuration options for default partials and swap wrapping.

  • Example Project & Demo: Overview of the reference Helpdesk application and sandbox.

  • API Reference: Complete function and class signatures.

  • Architectural Guide: Conceptual deep dive comparing 3 implementation variants and empirical benchmarks.