Targeting & Partials

This section covers request predicate helpers used with Swap(include_if=...) and request-scoped memoization utilities.

Request Targeting & Predicates (htmx_nav.targeting)

HTMX request-targeting: the Target condition type, predicates built from it, low-level HX-Target matching, and Target evaluation.

htmx_nav.targeting.Target = str | collections.abc.Callable[[django.http.request.HttpRequest], bool] | bool

Condition deciding whether a partial or swap applies to an HTMX request.

Examples

"main-content"  # Matches HX-Target header
targeting("main-content", "modal")
not_targeting("sidebar")
True
False
htmx_nav.targeting.has_messages(request)[source]

Check whether the request has pending Django messages.

Parameters:

request (HttpRequest) – The incoming HTTP request.

Return type:

bool

Returns:

True if pending messages exist in the storage backend.

Example

Swap(
    "partials/messages.html",
    target_id="messages",
    include_if=has_messages,
)
htmx_nav.targeting.htmx_target_is(request, *dom_ids)[source]

Check if the request’s HX-Target header matches any given DOM ID.

Parameters:

  • request (HttpRequest) – The incoming HTTP request.

  • *dom_ids (str) – DOM element IDs to match against (e.g., "content", "#content").

Return type:

bool

Returns:

True if the request target matches any provided ID.

Example

if htmx_target_is(request, "tab-content", "modal-body"):
    ...
htmx_nav.targeting.not_targeting(*dom_ids)[source]

Create a predicate checking that a request does not target specified DOM IDs.

Parameters:

*dom_ids (str) – DOM element IDs to exclude.

Return type:

Callable[[HttpRequest], bool]

Returns:

A callable taking HttpRequest and returning True if target does not match.

Example

Swap(
    "partials/sidebar.html",
    target_id="sidebar",
    include_if=not_targeting("main-content"),
)
htmx_nav.targeting.targeting(*dom_ids)[source]

Create a predicate checking if a request targets any specified DOM ID.

Parameters:

*dom_ids (str) – Target DOM element IDs to match against.

Return type:

Callable[[HttpRequest], bool]

Returns:

A callable taking HttpRequest and returning True if target matches.

Example

Swap(
    "partials/tabs.html",
    target_id="tabs",
    include_if=targeting("tab-content", "tabs"),
)

Partials (htmx_nav.partials)

PartialSpec: what template or block to render for a given HTMX request.

class htmx_nav.partials.PartialResolver(*args, **kwargs)[source]

Bases: Protocol

Derives a partial block or template path from the request and base template.

resolve(request, template_name)[source]

Resolve a partial block or template path given the request and base template.

Parameters:

  • request (HttpRequest) – The incoming HTTP request.

  • template_name (str) – The base template path specified by the view.

Return type:

str | None

Returns:

A block name (e.g. "#content"), a template path (e.g. "partials/_board.html"), or None to render the full template.

htmx_nav.partials.PartialSpec = str | collections.abc.Callable[[django.http.request.HttpRequest], str | None] | collections.abc.Mapping[str | htmx_nav.partials.PartialResolver, str | collections.abc.Callable[[django.http.request.HttpRequest], bool] | bool] | htmx_nav.partials.PartialResolver | None

Specifies what template or partial block to render for an HTMX request.

Values resolve to:

  • Block name ("#name"): Appended to the base template, giving template.html#name (Django 6 native {% partialdef %}).

  • Standalone path ("path/to/template.html"): Rendered in place of the base template.

  • PartialResolver (e.g. PathReplace): Derives a block name or path from the request and the base template name. Returns template_name unmodified if it cannot resolve the given template.

  • Callable (request) -> str | None: Returns a block name, template path, or None per request.

  • Mapping: Keys are block names, paths, or resolvers; values are Target conditions. The first key whose condition matches wins, so end with True for a fallback.

  • None: Forces a full-page render.

Examples

# Block name (single-file, Django 6 inline partial)
"#content"

# Standalone path
"partials/_tab_content.html"

# Block inside another template
"partials/navigation_components.html#sidebar"

# Derived path: base template "pages/board.html"
# renders "partials/_board.html" on HTMX requests
PathReplace("pages/", "partials/_")

# Per-request callable
lambda request: "#tab_content" if htmx_target_is(request, "tabs") else "#content"

# Mapping, first match wins, mixing every key kind
{
    "partials/_tab_content.html": targeting("tab-content"),
    PathReplace("pages/", "partials/_"): targeting("main-content"),
    "#content": True,  # fallback
}
class htmx_nav.partials.PathReplace(old, new)[source]

Bases: object

Swap a path segment or directory, e.g. "pages/" -> "partials/_".

Particularly useful in pre-Django 6 codebases or multi-file template layouts where full pages and partials live in separate directories.

Parameters:

  • old (str) – The path segment to match (e.g. "pages/").

  • new (str) – The replacement segment (e.g. "partials/_").

new
old
resolve(request, template_name)[source]

Derive a partial template path by replacing old with new.

If template_name does not contain old, returns template_name unmodified so non-matching templates fall back gracefully.

Return type:

str | None