Scenario	Component	Example
Initial page load, full content replacement	Skeleton screens	Parks list loading
Button actions, form submissions	Loading indicator (inline)	Submit button spinner
Partial content updates	Loading indicator (block)	Search results loading
Container replacement	Loading indicator (overlay)	Modal content loading

Components

loading_indicator.html

Standardized loading indicator for HTMX requests with three modes:

Inline Mode - For buttons and links:

<button hx-post="/api/action" hx-indicator="#btn-loading">
    Save
    {% include 'htmx/components/loading_indicator.html' with id='btn-loading' mode='inline' %}
</button>

Block Mode (default) - For content areas:

<div hx-get="/api/list" hx-indicator="#list-loading">
    <!-- Content -->
</div>
{% include 'htmx/components/loading_indicator.html' with id='list-loading' %}

Overlay Mode - For containers:

<div class="relative" hx-get="/api/data" hx-indicator="#overlay-loading">
    <!-- Content to cover -->
    {% include 'htmx/components/loading_indicator.html' with id='overlay-loading' mode='overlay' %}
</div>

Parameters

Parameter	Type	Default	Description
`id`	str	-	ID for hx-indicator targeting
`message`	str	"Loading..."	Loading text to display
`mode`	str	"block"	'inline', 'block', or 'overlay'
`size`	str	"md"	'sm', 'md', or 'lg'
`spinner`	str	"border"	'spin' (fa-spinner) or 'border' (CSS)

Skeleton Screens

Located in components/skeletons/, these provide content-aware loading placeholders:

Available Skeletons

Component	Use Case
`list_skeleton.html`	List views, search results
`card_grid_skeleton.html`	Card-based grid layouts
`detail_skeleton.html`	Detail/show pages
`form_skeleton.html`	Form loading states
`table_skeleton.html`	Data tables

Usage with HTMX

{# Initial content shows skeleton, replaced by HTMX #}
<div id="parks-list"
     hx-get="/parks/"
     hx-trigger="load"
     hx-swap="innerHTML">
    {% include 'components/skeletons/card_grid_skeleton.html' with cards=6 %}
</div>

With hx-indicator

<div id="results">
    <!-- Results here -->
</div>

{# Skeleton shown during loading #}
<div id="results-skeleton" class="htmx-indicator">
    {% include 'components/skeletons/list_skeleton.html' %}
</div>

Error Handling

error_message.html

Displays error messages with consistent styling:

{% include 'htmx/components/error_message.html' with
    message="Unable to load data"
    show_retry=True
    retry_url="/api/data"
%}

Parameters

Parameter	Type	Default	Description
`message`	str	-	Error message text
`code`	str	-	HTTP status code
`show_retry`	bool	False	Show retry button
`retry_url`	str	-	URL for retry action
`show_report`	bool	False	Show "Report Issue" link

Success Feedback

success_toast.html

Triggers a toast notification via HTMX response:

{% include 'htmx/components/success_toast.html' with
    message="Park saved successfully"
    type="success"
%}

Using HX-Trigger Header

From views, trigger toasts via response headers:

from django.http import HttpResponse

def save_park(request):
    # ... save logic ...
    response = HttpResponse()
    response['HX-Trigger'] = json.dumps({
        'showToast': {
            'type': 'success',
            'message': 'Park saved successfully'
        }
    })
    return response

HTMX Configuration

The base template configures HTMX with:

30-second timeout
Global view transitions enabled
Template fragments enabled
Comprehensive error handling

Swap Strategies

Strategy	Use Case
`innerHTML`	Replace content inside container (lists, search results)
`outerHTML`	Replace entire element (status badges, individual items)
`beforeend`	Append items (infinite scroll)
`afterbegin`	Prepend items (new items at top)

Target Naming Conventions

#object-type-id - For specific objects (e.g., #park-123)
#section-name - For page sections (e.g., #results, #filters)
#modal-container - For modals
this - For self-replacement

Custom Events

{model}-status-changed - Status updates (e.g., park-status-changed)
auth-changed - Authentication state changes
{model}-created - New item created
{model}-updated - Item updated
{model}-deleted - Item deleted

Best Practices

Always specify hx-indicator for user feedback
Use skeleton screens for initial page loads and full content replacement
Use inline indicators for button actions
Use overlay indicators for modal content loading
Add aria attributes for accessibility (role="status", aria-busy)
Clean up loading states after request completion (automatic with HTMX)