Getting Started with htmxr

What is htmxr?

htmx is a lightweight JavaScript library (~16kb) that lets any HTML element send HTTP requests — not just <a> and <form> tags.

The core philosophy is HTML over the wire: your server returns HTML fragments, not JSON. The browser swaps those fragments directly into the page without a full reload.

htmxr is the R wrapper: it provides htmltools-based primitives to generate htmx attributes and build complete pages, backed by a plumber2 server.

Installation

install.packages("htmxr")

# development version
pak::pak("hyperverse-r/htmxr")

htmxr uses plumber2 as its HTTP server — make sure it is installed alongside htmxr.

How htmx works

Every htmx interaction follows the same four-step cycle:

1. User triggers an event — a click, an input change, a page load, a form submission…
2. htmx sends an HTTP request to your server (GET or POST)
3. Your server returns an HTML fragment — a snippet of HTML, not JSON
4. htmx swaps the fragment into the targeted DOM element

You control this cycle through five core attributes:

In htmxr, these map directly to function parameters — no JavaScript to write.

Your first htmxr app

The fastest way to see htmxr in action is to run the built-in hello example:

library(htmxr)
hx_run_example("hello")

This launches an Old Faithful histogram where a slider controls the number of bins. Let’s walk through how it works.

hx_slider_input(
  id = "bins",
  label = "Number of bins:",
  value = 30,
  min = 1,
  max = 50,
  get = "/plot",                         # send GET /plot on trigger
  trigger = "input changed delay:300ms", # trigger: input event, debounced 300ms
  target = "#plot"                       # replace the content of #plot
)

tags$div(id = "plot") |>
  hx_set(
    get = "/plot",
    trigger = "load",       # fires once when the element is loaded
    target = "#plot",
    swap = "innerHTML"
  )

#* @get /plot
#* @query bins:integer(30)
#* @parser none
#* @serializer none
function(query) {
  generate_plot(query$bins)
}

slider input event
       │
       ▼
GET /plot?bins=35   ──►   server renders SVG
                                   │
                    ◄──────────────┘
          htmx swaps SVG into #plot

Anatomy of an htmxr project

A minimal htmxr app needs only two things:

api.R — your plumber2 API with two kinds of routes:

• GET / — returns the full page (built with hx_page())

• GET /fragment — returns HTML fragments (one route per dynamic piece)

hx_serve_assets() — registers the htmx JavaScript file as a static asset on your plumber2 router. hx_page() and hx_head() handle injecting the <script> tag automatically.

# Minimal api.R structure
library(htmxr)

#* @get /
#* @serializer html
function() {
  hx_page(
    hx_head(
      title = "My app"
    ),
    tags$div(
      id = "content"
    ) |>
      hx_set(
        get = "/content",
        trigger = "load",
        target = "#content"
      )
  )
}

#* @get /content
#* @serializer html
function() {
  tags$p("Hello from the server!")
}

Launch API with:

library(htmxr)

pr <- plumber2::api("api.R") |>
  hx_serve_assets()

cat("\n🚀 Launch API...\n")
cat("🌐 Webapp: http://127.0.0.1:8080/\n\n")

pr$ignite(port = 8080)

Next steps

Explore more built-in examples:

# List all available examples
hx_run_example()

# Dynamic table filtering with hx_select_input()
hx_run_example("select-input")