hx/hx_header

HTMX Response Headers

This module provides functions for setting HTMX-specific HTTP response headers. These headers allow the server to control HTMX behavior on the client-side, enabling powerful server-driven interactions without writing JavaScript.

Framework Integration

This module is framework-agnostic and returns standard #(String, String) tuples that can be used with any Gleam web framework:

Wisp

import hx/hx_header
import wisp

pub fn handler(req) {
  let #(name, value) = hx_header.trigger([
    hx_header.SimpleTrigger("reload")
  ])

  wisp.ok()
  |> wisp.set_header(name, value)
  |> wisp.html_body("<div>Updated</div>")
}

gleam_http

import hx/hx_header
import gleam/http/response as http_response

pub fn handler(req) {
  let #(name, value) = hx_header.redirect("/login")

  http_response.new(200)
  |> http_response.set_header(name, value)
  |> http_response.set_body("<div>Redirecting...</div>")
}

Response Header Reference

For complete documentation of HTMX response headers, see:

Types

LocationConfig

</>

Configuration for HX-Location header with client-side redirect options.

This type represents all the options available for the HX-Location header, which performs a client-side redirect using HTMX navigation.

Use the builder pattern to construct this type:

let config =
  hx_header.location_config("/dashboard")
  |> hx_header.target("#main")
  |> hx_header.swap("innerHTML")

pub type LocationConfig {
  LocationConfig(
    path: String,
    source: option.Option(String),
    event: option.Option(String),
    target: option.Option(String),
    swap: option.Option(String),
    values: option.Option(json.Json),
  )
}

Constructors

LocationConfig(
  path: String,
  source: option.Option(String),
  event: option.Option(String),
  target: option.Option(String),
  swap: option.Option(String),
  values: option.Option(json.Json),
)

TriggerEvent

</>

Trigger event for HX-Trigger headers.

HTMX supports two types of trigger events:

SimpleTrigger: Just an event name with no additional data
DetailedTrigger: An event name with a JSON details payload

pub type TriggerEvent {
  SimpleTrigger(name: String)
  DetailedTrigger(name: String, details: json.Json)
}

Constructors

```
SimpleTrigger(name: String)
```
Simple event name with no additional data

DetailedTrigger(name: String, details: json.Json)

Event with JSON details payload

Values

event

</>

pub fn event(
  config: LocationConfig,
  event: String,
) -> LocationConfig

Sets the event that triggered the navigation.

Example

hx_header.location_config("/page")
|> hx_header.event("click")

location

</>

pub fn location(url: String) -> #(String, String)

Returns HX-Location header for a simple client-side redirect.

This performs a client-side redirect using HTMX navigation to the specified URL.

Official Documentation

Example

let #(name, value) = hx_header.location("/dashboard")
wisp.ok()
|> wisp.set_header(name, value)

location_config

</>

pub fn location_config(path: String) -> LocationConfig

Creates a new LocationConfig with the specified path.

Use the builder functions to add additional options.

Example

let config =
  hx_header.location_config("/dashboard")
  |> hx_header.target("#main")
  |> hx_header.swap("innerHTML")

location_with

</>

pub fn location_with(
  config config: LocationConfig,
) -> #(String, String)

Returns HX-Location header with advanced options.

This allows you to specify additional options for the client-side redirect, such as target element, swap strategy, event source, and additional values.

Official Documentation

Example

let config =
  hx_header.location("/dashboard")
  |> hx_header.with_target("#main")
  |> hx_header.with_swap("innerHTML")

let #(name, value) = hx_header.location_with(config)
wisp.ok()
|> wisp.set_header(name, value)

push_url

</>

pub fn push_url(url: String) -> #(String, String)

Returns HX-Push-Url header to push a URL into the browser history.

This updates the browser’s address bar without performing a full page reload.

Official Documentation

Example

let #(name, value) = hx_header.push_url("/new-path")
wisp.ok()
|> wisp.set_header(name, value)

redirect

</>

pub fn redirect(url: String) -> #(String, String)

Returns HX-Redirect header for a full page redirect.

This will cause the browser to perform a full page reload to the specified URL, replacing the current page entirely.

Official Documentation

Example

let #(name, value) = hx_header.redirect("/login")
wisp.ok()
|> wisp.set_header(name, value)

refresh

</>

pub fn refresh() -> #(String, String)

Returns HX-Refresh header to refresh the page.

This will cause the client to perform a full page refresh.

Official Documentation

Example

let #(name, value) = hx_header.refresh()
wisp.ok()
|> wisp.set_header(name, value)

replace_url

</>

pub fn replace_url(url: String) -> #(String, String)

Returns HX-Replace-Url header to replace the current URL in browser history.

This updates the browser’s address bar by replacing the current history entry.

Official Documentation

Example

let #(name, value) = hx_header.replace_url("/updated-path")
wisp.ok()
|> wisp.set_header(name, value)

reselect

</>

pub fn reselect(selector: String) -> #(String, String)

Returns HX-Reselect header to change the selected content.

This allows you to choose a different part of the response to swap in.

Official Documentation

Example

let #(name, value) = hx_header.reselect("#content")
wisp.ok()
|> wisp.set_header(name, value)

reswap

</>

pub fn reswap(swap: String) -> #(String, String)

Returns HX-Reswap header to change the swap strategy.

This overrides the swap strategy specified on the element. Valid values include: innerHTML, outerHTML, beforebegin, afterbegin, beforeend, afterend, delete, none.

Official Documentation

Example

let #(name, value) = hx_header.reswap("outerHTML")
wisp.ok()
|> wisp.set_header(name, value)

retarget

</>

pub fn retarget(selector: String) -> #(String, String)

Returns HX-Retarget header to change the target element.

This overrides the target element specified on the original element.

Official Documentation

Example

let #(name, value) = hx_header.retarget("#different-element")
wisp.ok()
|> wisp.set_header(name, value)

source

</>

pub fn source(
  config: LocationConfig,
  source: String,
) -> LocationConfig

Sets the source element for the location redirect.

Example

hx_header.location_config("/page")
|> hx_header.source("#button-1")

swap

</>

pub fn swap(
  config: LocationConfig,
  swap: String,
) -> LocationConfig

Sets the swap strategy for the location redirect.

Example

hx_header.location_config("/page")
|> hx_header.swap("outerHTML")

target

</>

pub fn target(
  config: LocationConfig,
  target: String,
) -> LocationConfig

Sets the target element for the location redirect.

Example

hx_header.location_config("/page")
|> hx_header.target("#content")

trigger

</>

pub fn trigger(events: List(TriggerEvent)) -> #(String, String)

Returns HX-Trigger header to trigger client-side events.

This triggers events on the client-side immediately after receiving the response. Events can be simple (just a name) or detailed (with a JSON payload).

Official Documentation

Examples

Simple event:

let #(name, value) = hx_header.trigger([
  hx_header.SimpleTrigger("reload")
])
wisp.ok()
|> wisp.set_header(name, value)

Event with details:

let details = json.object([
  #("message", json.string("Success!")),
  #("level", json.string("info"))
])

let #(name, value) = hx_header.hx_trigger([
  hx_header.DetailedTrigger("showNotification", details)
])
wisp.ok()
|> wisp.set_header(name, value)

Multiple events:

let #(name, value) = hx_header.trigger([
  hx_header.SimpleTrigger("reload"),
  hx_header.SimpleTrigger("clearForm")
])
wisp.ok()
|> wisp.set_header(name, value)

trigger_after_settle

</>

pub fn trigger_after_settle(
  events: List(TriggerEvent),
) -> #(String, String)

Returns HX-Trigger-After-Settle header to trigger events after the settle phase.

This triggers events after the settle phase has completed.

Official Documentation

Example

let #(name, value) = hx_header.trigger_after_settle([
  hx_header.SimpleTrigger("scrollToTop")
])
wisp.ok()
|> wisp.set_header(name, value)

trigger_after_swap

</>

pub fn trigger_after_swap(
  events: List(TriggerEvent),
) -> #(String, String)

Returns HX-Trigger-After-Swap header to trigger events after the swap phase.

This triggers events after the swap has occurred but before the settle phase.

Official Documentation

Example

let #(name, value) = hx_header.trigger_after_swap([
  hx_header.SimpleTrigger("highlightNew")
])
wisp.ok()
|> wisp.set_header(name, value)

values

</>

pub fn values(
  config: LocationConfig,
  values: json.Json,
) -> LocationConfig

Sets additional values to include with the location redirect.

Example

let values = json.object([
  #("userId", json.int(123))
])

hx_header.location_config("/page")
|> hx_header.values(values)