htmx

package
v1.8.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 9, 2026 License: MIT Imports: 8 Imported by: 2

Documentation

Overview

Package htmx provides HTMX integration helpers including error handling patterns and response utilities for building dynamic web applications.

templ: version: v0.3.1020

templ: version: v0.3.1020

templ: version: v0.3.1020

templ: version: v0.3.1020

templ: version: v0.3.1020

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func CSRFToken 

func CSRFToken(token string) templ.Component

CSRFToken renders a hidden input for HTMX forms with CSRF protection 

@htmx.CSRFToken("csrf_token_value")

func ConfirmDelete 

func ConfirmDelete(props ConfirmDeleteProps) templ.Component

ConfirmDelete renders a button with a confirmation dialog for destructive actions 

@htmx.ConfirmDelete(htmx.ConfirmDeleteProps{Delete: "/delete/123", Target: "#item-123", Confirm: "Are you sure?"})

func GlobalErrorHandling 

func GlobalErrorHandling(cfg ErrorHandlingConfig) templ.Component

GlobalErrorHandling renders a comprehensive global HTMX error handling script. Include this once in your base layout, ideally at the end of the body. Requires feedback.ToastContainer on the page for accessible error announcements (aria-live). If ToastContainer is not present, errors are only logged to the console.

Typical layout wiring: 

@layout.Base(layout.PageProps{...}) {
    @feedback.ToastContainer(nonce)  // must be present for toast error feedback
    // ... page content ...
    @htmx.GlobalErrorHandling(htmx.DefaultErrorHandlingConfig())
}

func InlineLoadingOverlay 

func InlineLoadingOverlay(id string, spinner templ.Component) templ.Component

InlineLoadingOverlay renders a localized loading overlay for HTMX targets. Accepts a spinner component for decoupled loading animation. 

@htmx.InlineLoadingOverlay("tc-form-loading", feedback.Spinner(feedback.SpinnerProps{Size: feedback.SpinnerMD, Color: "text-blue-600 dark:text-blue-400"}))

func LoadingButton 

func LoadingButton(defaultText, loadingText string, spinner templ.Component) templ.Component

LoadingButton renders a button with built-in loading state. The default text hides during an HTMX request (htmx-request on the form toggles htmx-indicator visibility); loadingText is the htmx-indicator. 

<button class="btn-primary" hx-post="/save" hx-indicator=".tc-btn-loading">
   @htmx.LoadingButton("Save", "Saving...", feedback.Spinner(feedback.SpinnerProps{Size: feedback.SpinnerSM, Color: "htmx-indicator"}))
</button>

func LoadingIndicator 

func LoadingIndicator(spinner templ.Component) templ.Component

LoadingIndicator renders a fixed-position HTMX loading indicator. Accepts a spinner component for decoupled loading animation. 

@htmx.LoadingIndicator(feedback.Spinner(feedback.SpinnerProps{Size: feedback.SpinnerLG, Color: "text-blue-600 dark:text-blue-400"}))

func PolledLiveIsValid added in v1.5.0 

func PolledLiveIsValid(v PolledLive) bool

PolledLiveIsValid reports whether v is one of the defined PolledLive constants.

func PolledRegion added in v1.5.0 

func PolledRegion(props PolledRegionProps) templ.Component

PolledRegion renders a div that auto-refreshes its content via HTMX polling on an interval. The region replaces itself (hx-swap="outerHTML") on each poll, which means the children re-render server-side on every request.

Include a "Updated HH:MM:SS" timestamp (ShowTimestamp: true) so operators can verify polling is active — if the timestamp freezes, polling has stalled. 

@htmx.PolledRegion(htmx.PolledRegionProps{URL: "/partials/stats", Every: "10s", Eager: true}) {
   @display.StatCard(display.StatCardProps{Label: "Messages", Value: "1,234"})
}

func SwapOOB 

func SwapOOB(props SwapOOBProps) templ.Component

SwapOOB renders an out-of-band swap wrapper for HTMX responses. Use this to update multiple elements in a single response. Invalid swap styles fall back to outerHTML. 

@htmx.SwapOOB(htmx.SwapOOBProps{Selector: "#toast-container", SwapStyle: htmx.SwapBeforeEnd}) {
   @feedback.Toast(props)
 }

func SwapStyleIsValid added in v0.8.0 

func SwapStyleIsValid(v SwapStyle) bool

SwapStyleIsValid reports whether v is one of the defined SwapStyle constants.

func ViewTransitions added in v0.18.0 

func ViewTransitions(props ViewTransitionsProps) templ.Component

ViewTransitions renders a CSP-safe script that enables native View Transitions for HTMX swaps, plus default transition CSS.

Place this component once per page, typically in the <head> or at the end of <body> before other HTMX-using components. 

@htmx.ViewTransitions(htmx.ViewTransitionsProps{Global: true})

Types

type ConfirmDeleteProps added in v0.6.0 

type ConfirmDeleteProps struct {
	utils.BaseProps
	Delete  string
	Target  string
	Confirm string
}

ConfirmDeleteProps configures a confirmation delete button.

type ErrorHandlingConfig 

type ErrorHandlingConfig struct {
	// Nonce is the CSP nonce for inline scripts
	Nonce string
	// MaxErrorHistory is the maximum number of errors to track (default: 10)
	MaxErrorHistory int
	// MaxRetries is the maximum number of retry attempts for server errors (default: 2)
	MaxRetries int
	// RetryDelayMS is the base delay in milliseconds between retries, multiplied by retry count (default: 1000)
	RetryDelayMS int
}

ErrorHandlingConfig configures the global HTMX error handling behavior

func DefaultErrorHandlingConfig 

func DefaultErrorHandlingConfig() ErrorHandlingConfig

DefaultErrorHandlingConfig returns sensible defaults for error handling

type PolledLive added in v1.5.0 

type PolledLive string

PolledLive is the aria-live politeness setting for a polled region. 

const (
	// PolledLivePolite announces updates after the current speech finishes (default).
	PolledLivePolite PolledLive = "polite"
	// PolledLiveAssertive announces updates immediately, interrupting current speech.
	PolledLiveAssertive PolledLive = "assertive"
	// PolledLiveOff disables screen-reader announcements for this region.
	PolledLiveOff PolledLive = "off"
)

type PolledRegionProps added in v1.5.0 

type PolledRegionProps struct {
	utils.BaseProps

	// URL is the HTMX endpoint to fetch for refreshing the region content.
	URL string

	// Every is the poll interval as an HTMX timing string (e.g. "10s", "2m", "500ms").
	Every string

	// Eager fires the first fetch on initial load in addition to polling.
	// When false, the first fetch happens after the first interval elapses.
	// Ignored when Trigger is set.
	Eager bool

	// Trigger overrides the auto-generated hx-trigger value. When set,
	// Every and Eager are ignored and this string is used verbatim as
	// hx-trigger. Useful for custom triggers like SSE events
	// (e.g. "stats-refresh from:body").
	Trigger string

	// Swap controls how the fetched content replaces the region.
	// Defaults to SwapOuterHTML.
	Swap SwapStyle

	// Live sets the aria-live politeness for screen-reader announcements.
	// Defaults to PolledLivePolite.
	Live PolledLive

	// ShowTimestamp renders a "Updated HH:MM:SS" footer so operators can see
	// at a glance that polling is active (the timestamp ticks forward on each
	// successful poll because the whole region re-renders).
	ShowTimestamp bool

	// TimeFormat is the Go time format string for the timestamp footer.
	// Default: "15:04:05" (time-only). Use time.RFC3339 for full date+time.
	TimeFormat string
}

PolledRegionProps configures an auto-refreshing HTMX region.

func DefaultPolledRegionProps added in v1.5.0 

func DefaultPolledRegionProps() PolledRegionProps

DefaultPolledRegionProps returns sensible defaults for a polled region.

type SwapOOBProps added in v0.6.0 

type SwapOOBProps struct {
	utils.BaseProps
	Selector  string
	SwapStyle SwapStyle
}

SwapOOBProps configures an out-of-band swap wrapper.

type SwapStyle added in v0.6.0 

type SwapStyle string

SwapStyle is an HTMX swap style for out-of-band updates. 

const (
	SwapInnerHTML   SwapStyle = "innerHTML"
	SwapOuterHTML   SwapStyle = "outerHTML"
	SwapBeforeBegin SwapStyle = "beforebegin"
	SwapAfterBegin  SwapStyle = "afterbegin"
	SwapBeforeEnd   SwapStyle = "beforeend"
	SwapAfterEnd    SwapStyle = "afterend"
	SwapDelete      SwapStyle = "delete"
	SwapNone        SwapStyle = "none"
)

HTMX swap styles (https://htmx.org/attributes/hx-swap/).

type ViewTransitionsProps added in v0.18.0 

type ViewTransitionsProps struct {
	utils.BaseProps

	// Global enables View Transitions for ALL HTMX swaps on the page.
	// When false, consumers opt in per-element via hx-swap="... transition:true".
	Global bool
}

ViewTransitionsProps configures native View Transitions API integration for HTMX content swaps.

The View Transitions API provides smooth, animated transitions between DOM states — cross-fades, shared-element morphing, and custom animations — with zero JavaScript beyond enabling the feature.

HTMX 2.0 supports View Transitions natively. This component:

  • Optionally enables View Transitions globally for all HTMX swaps
  • Renders CSS for default and customizable transition animations

Graceful degradation: browsers without View Transitions support (older Firefox/Safari) perform instant swaps — identical to current behavior.

func DefaultViewTransitionsProps added in v0.18.0 

func DefaultViewTransitionsProps() ViewTransitionsProps

DefaultViewTransitionsProps returns sensible defaults.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.