htmx

README

Go HTMX

A helper library for using HTMX with templ in Go.

Import

import (
	"go.teddydd.me/htmx"
)

Example

There is an example app using most of this library features. See ./example/ directory.

Contributing

The source code is avaliable on https://git.sr.ht/~teddy/htmx-go

Send patches here: https://lists.sr.ht/~teddy/public-inbox

Documentation

Index

• Constants
• func DetectMiddleware(next http.Handler, notHTMX http.Handler) http.Handler
• func Merge(attrs ...templ.Attributes) templ.Attributes
• func OOB(ctx context.Context, id string) templ.Attributes
• func Render(ctx context.Context, w io.Writer, c templ.Component, oob ...templ.Component) error
• func RequestMiddleware(next http.Handler) http.Handler
• func ResponseMiddleware(httpWriterErrorHandler func(error)) func(http.Handler) http.Handler
• func WithContext(ctx context.Context, h Context) context.Context
• func WithOOB(ctx context.Context, oob bool) context.Context
• type Context
  • func Ctx(ctx context.Context) Context
• type Request
  • func FromRequest(r *http.Request) Request
• type Response
  • func (r *Response) Apply(w http.ResponseWriter)
  • func (r *Response) Reswap(s Swap, mods ...SwapModifier)
• type ScrollShowValue
• type Swap
• type SwapModifier
  • func FocusScrollModifier() SwapModifier
  • func IgnoreTitleModifier() SwapModifier
  • func ScrollModifier(v ScrollShowValue, cssSelector ...string) SwapModifier
  • func SettleModifier(duration string) SwapModifier
  • func ShowModifier(v ScrollShowValue, cssSelector ...string) SwapModifier
  • func SwapTimingModifier(duration string) SwapModifier
  • func TransitionModifier() SwapModifier
  • func (s SwapModifier) String() string

Constants

const WindowCSSSelector = "window"

WindowCSSSelector can be used in ScrollModifier or ShowModifier instead of CSS selector to scroll to the top and bottom of the current window.

Functions

func DetectMiddleware

func DetectMiddleware(next http.Handler, notHTMX http.Handler) http.Handler

DetectMiddleware blocks request not issued by the HTMX library (lacking HTMX specific headers).

func Merge

func Merge(attrs ...templ.Attributes) templ.Attributes

Merge is utility for combining multiple templ.Attributes. Repeating attribute keys result in undefined behaviour.

<p {htmx.Merge(htmx.OOB(ctx, "some ID"), map[string]any{"style": "color: green;"})...}>

func OOB

func OOB(ctx context.Context, id string) templ.Attributes

OOB return id and hx-swap-oob attributes that you can use in templ. If context is marked as out of band then the component will have hx-swap-oob set to true. To be used with Render.

<p {htmx.OOB(ctx,"foo")...}>Element with ID foo</p>

func Render

func Render(
	ctx context.Context,
	w io.Writer,
	c templ.Component,
	oob ...templ.Component,
) error

Render given component, optionally attaching one or more out of band components. OOB component must use OOB function or have hx-swap-oob set manually. Component can be nil if you want to render only OOB component.

func RequestMiddleware

func RequestMiddleware(next http.Handler) http.Handler

RequestMiddleware is middleware that reads HX-* headers into structure and embeds it into context. The information can be recieved in handler with Ctx function.

func ResponseMiddleware

func ResponseMiddleware(
	httpWriterErrorHandler func(error),
) func(http.Handler) http.Handler

ResponseMiddleware is middleware that copies settings from Response struct to http.ResponseWriter headers.

This middleware requires RequestMiddleware higher in the middleware stack.

Response struct can be accessed from Context via Ctx function in handler.

This middleware intercepts the response so it can write headers before data. It should not be used on routes that require streaming, long pooling or huge downloads.

httpWriterErrorHandler can be nil. It's called when writing response to underlying http.ResponseWriter fails.

func WithContext

func WithContext(ctx context.Context, h Context) context.Context

WithContext embeds Context into context.Context.

func WithOOB

func WithOOB(ctx context.Context, oob bool) context.Context

WithOOB marks context for out of band template rendering. Components using this context and OOB will have hx-swap-oob set to true.

Types

type Context

type Context struct {
	Request
	Response *Response
}

Context contains information about HTMX request as well as Response struct for setting the response headers.

func Ctx

func Ctx(ctx context.Context) Context

Ctx extracts HTMX Context from context.Context.

type Request

type Request struct {
	// HX-Boosted: indicates that the request is via an element using hx-boost
	Boosted bool
	// HX-Current-URL: the current URL of the browser
	CurrentURL string
	// HX-History-Restore-Request: “true” if the request is for history restoration after a miss in the local history cache
	HistoryRestoreRequest bool
	// HX-Prompt: the user response to an hx-prompt
	Prompt string
	// HX-Request: always “true” for HTMX requests
	Request bool
	// HX-Target: the id of the target element if it exists
	Target string
	// HX-Trigger-Name: the name of the triggered element if it exists
	TriggerName string
	// HX-Trigger: the id of the triggered element if it exists
	Trigger string
}

Request is information provided via the headers by HTMX https://htmx.org/reference/#request_headers

func FromRequest

func FromRequest(r *http.Request) Request

FromRequest reads HTMX headers from http.Request

type Response

type Response struct {
	// HX-Location: allows you to do a client-side redirect that does not do a full page reload
	Location string
	// HX-Push-Url: pushes a new url into the history stack
	PushUrl string
	// HX-Redirect: can be used to do a client-side redirect to a new location
	Redirect string
	// HX-Refresh: if set to “true” the client-side will do a full refresh of the page
	Refresh bool
	// HX-Replace-Url: replaces the current URL in the location bar
	ReplaceUrl string

	// HX-Retarget: a CSS selector that updates the target of the content update to a different element on the page
	Retarget string
	// HX-Reselect: a CSS selector that allows you to choose which part of the response is used to be swapped in. Overrides an existing hx-select on the triggering element
	Reselect string
	// HX-Trigger: allows you to trigger client-side events
	Trigger string
	// HX-Trigger-After-Settle: allows you to trigger client-side events after the settle step
	TriggerAfterSettle string
	// HX-Trigger-After-Swap: allows you to trigger client-side events after the swap step
	TriggerAfterSwap string
	// contains filtered or unexported fields
}

Response can be used to set headers understood by the HTMX.

func (*Response) Apply

func (r *Response) Apply(w http.ResponseWriter)

Apply response data to headers. It needs to be called before writing any data.

func (*Response) Reswap

func (r *Response) Reswap(s Swap, mods ...SwapModifier)

Reswap sets HX-Reswap header. HX-Reswap allows you to specify how the response will be swapped. See hx-swap for possible values.

type ScrollShowValue

type ScrollShowValue = string

const (
	Top    ScrollShowValue = "top"
	Bottom ScrollShowValue = "bottom"
)

type Swap

type Swap string

The hx-swap attribute allows you to specify how the response will be swapped in relative to the target of an AJAX request. https://htmx.org/attributes/hx-swap/

const (
	// Replace the inner html of the target element
	SwapInnerHTML Swap = "innerHTML"
	// Replace the entire target element with the response
	SwapOuterHTML Swap = "outerHTML"
	// Insert the response before the target element
	SwapBeforeBegin Swap = "beforebegin"
	// Insert the response before the first child of the target element
	SwapAfterBegin Swap = "afterbegin"
	// Insert the response after the last child of the target element
	SwapBeforeEnd Swap = "beforeend"
	// Insert the response after the target element
	SwapAfterEnd Swap = "afterend"
	// Deletes the target element regardless of the response
	SwapDelete Swap = "delete"
	// Does not append content from response (out of band items will
	// still be processed).
	SwapNone Swap = "none"
)

type SwapModifier

type SwapModifier struct {
	Name      string
	StrValue  string
	BoolValue bool
}

func FocusScrollModifier

func FocusScrollModifier() SwapModifier

func IgnoreTitleModifier

func IgnoreTitleModifier() SwapModifier

func ScrollModifier

func ScrollModifier(v ScrollShowValue, cssSelector ...string) SwapModifier

func SettleModifier

func SettleModifier(duration string) SwapModifier

func ShowModifier

func ShowModifier(v ScrollShowValue, cssSelector ...string) SwapModifier

func SwapTimingModifier

func SwapTimingModifier(duration string) SwapModifier

func TransitionModifier

func TransitionModifier() SwapModifier

func (SwapModifier) String

func (s SwapModifier) String() string