Settings

All settings are optional and configured in your Django settings.py.

Setting

Default

Description

HTMX_NAV_DEFAULT_PARTIAL

"#content"

Default partial block or template path when partial is omitted.

HTMX_NAV_DEFAULT_SWAP_WRAP

"oob"

Default HTML wrapper for out-of-band swaps ("oob" or "hx-partial").

HTMX_NAV_TITLE_CONTEXT_KEY

"title"

Context key used for automatic <title> element injection.

HTMX_NAV_DEBUG_SWAPS

False

Enables visual swap animations during development.

HTMX_NAV_DEFAULT_PARTIAL

  • Type: str | PartialResolver | None (or any PartialSpec)

  • Default: "#content"

  • Applies to: render_nav, make_shell_renderer, make_shell_view_mixin

Specifies the fallback partial block, template path, or resolver when a view does not explicitly pass partial=....

Template Block Extraction (Single-File)

When templates define partials internally using {% block ... %} (or {% partialdef %}):

# settings.py
HTMX_NAV_DEFAULT_PARTIAL = "#main"

Path Replacement (Multi-File)

When pages and partials are separate files (e.g. pages/x.html and partials/_x.html), configure PathReplace:

# settings.py
from htmx_nav import PathReplace

HTMX_NAV_DEFAULT_PARTIAL = PathReplace("pages/", "partials/_")

See Separate page and partial files (PathReplace) in the Targeting Guide for details.

To completely bypass partial extraction for full-page renders while keeping out-of-band swaps, pass partial=None directly to render_nav.

HTMX_NAV_DEFAULT_SWAP_WRAP

  • Type: Literal["oob", "hx-partial"]

  • Default: "oob"

  • Applies to: Swap, Swap.text

Controls how out-of-band swap fragments are wrapped in HTML when wrap is not specified on the Swap:

  • "oob": Standard HTMX swap using <div id="..." hx-swap-oob="...">.

  • "hx-partial": Custom element wrapper using <hx-partial hx-target="#..." hx-swap="...">.

# settings.py
HTMX_NAV_DEFAULT_SWAP_WRAP = "hx-partial"

HTMX_NAV_TITLE_CONTEXT_KEY

  • Type: str

  • Default: "title"

  • Applies to: render_nav, make_shell_view_mixin

The template context variable name used for page titles. Set this to match the variable name used in your base.html title tag:

<!-- base.html -->
<title>{% block title %}{{ page_title|default:"Home Page" }}{% endblock %}</title>

# settings.py
HTMX_NAV_TITLE_CONTEXT_KEY = "page_title"

This keeps page titles in sync across both request modes:

  • Full-page reloads: Passing title="Dashboard" to render_nav populates context["page_title"], which base.html renders.

  • HTMX requests: render_nav reads context["page_title"] and appends an escaped <title> tag to the response, which HTMX automatically applies to the browser tab.

HTMX_NAV_DEBUG_SWAPS

  • Type: bool

  • Default: False

  • Applies to: Swap.render, debug_swap_marker

When True, appends a small inline <script> to swapped fragments that adds the hn-swap CSS class to the target DOM element, triggering a highlight animation.

django-htmx-nav checks HTMX_NAV_DEBUG_SWAPS directly without inspecting Django’s DEBUG setting. This independence allows you to enable debug swaps in staging or demo environments even when DEBUG = False.

See the Debugging Guide for CSS integration and custom styling.