Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 28 ยท HTMX Basics

Your First HTMX Request

Send your first HTMX request with hx-get, choose where the reply goes with hx-target, see the default swap, and learn why the server answers with HTML, not JSON.

Time to meet HTMX properly. Its whole idea fits in one sentence: an element sends a request, the server replies with a piece of HTML, and HTMX puts that HTML into the page. There is no fetch() call to write, no JSON to parse and no template to render in JavaScript. You describe the behavior with attributes.

In this lesson you will make your first request with hx-get, aim the reply with hx-target, see what hx-swap does by default, look at the headers HTMX adds to every request, and understand the mock server that powers the examples in this track. You can read about the setup in the previous chapter's lessons, but nothing here requires more than basic HTML.

The request cycle

Every HTMX interaction has the same four steps.

sequenceDiagram
    participant U as User
    participant H as HTMX in the page
    participant S as Server
    U->>H: Clicks a button with hx-get
    H->>S: GET /clock with HX-Request header
    S-->>H: 200 OK and an HTML fragment
    H->>H: Swaps the fragment into the target
    H-->>U: Only that part of the page changed

The request cycle: trigger, request, HTML response, swap.

The important word is fragment. The server does not send a whole page with <html> and <head>. It sends just the piece that should change, for example <p>It is 10:42.</p>.

hx-get and hx-target

Add hx-get="/url" to any element and, by default, a click sends a GET request to that URL (forms and inputs have different default triggers, covered in the next lesson). hx-target is a CSS selector that says which element receives the reply. Without it, the element that made the request is the target.

hx-get with hx-target

Click the button a few times. The text in the dashed box is replaced each time, and the number comes from the server's memory (a variable in the mock server), so you know it really made a round trip. The page never reloads and your scroll position does not change.

In your own project you would not need the mock server. The URL /hello would be a real route in Laravel, Express, Django or any backend that returns HTML.

What the server sees

HTMX adds headers to each request so the server can recognize it. The most useful ones:

Header Meaning
HX-Request Always true for HTMX requests
HX-Target The id of the target element, if it has one
HX-Trigger The id of the element that triggered the request
HX-Current-URL The page URL when the request was sent

A common server trick is to check HX-Request and return just a fragment for HTMX but a full page for a normal browser visit. The same URL then works with and without JavaScript. The server-side lesson shows this in four frameworks.

The mock server passes headers to your handler in lowercase. This demo echoes some of them back:

Peek at the request headers

You should see hx-request: true, hx-target: result and hx-trigger: inspect. HTMX read the ids from the DOM for you. If the trigger button had no id, hx-trigger would be empty and a header would be missing.

HTML, not JSON

With fetch, a typical flow is: request JSON, parse it, create elements, insert them. With HTMX, the server builds the markup:

HTML
<!-- the whole response body, not a page -->
<li class="task done">Buy milk</li>

HTMX takes the response text, parses it as HTML and swaps it into the target. If your server returned JSON like {"name":"Ann"}, HTMX would insert that text literally. It is not magic: it expects HTML. That is a feature. The knowledge of how things look stays in one place, your server templates, and the browser only needs to know where things go.

Because the response becomes part of your page, escape any user data before putting it in a fragment. A comment containing <script> must never reach the page unescaped. The server-side lesson covers this in detail.

The default swap: innerHTML

By default HTMX replaces the inner content of the target (the innerHTML swap). The target element itself stays in place with its attributes and id, and only what is inside it changes. Other swap styles (replace the element itself, append, prepend and more) are the subject of targets and swaps.

Next to the swap, HTMX also manages CSS classes while the request runs. While waiting, the triggering element gets the class htmx-request, which you can use to show a spinner. You will use that in loading states.

Many requests, one page

You are not limited to one request per page. Any number of elements can have hx-get. In the next demo, three buttons share a single target, and the "server" has three routes. The mock server picks a handler using the method and path, just as a real router would.

One target, three routes

Each route returns a different fragment, all swapped into #panel. You have just built tabs without writing a line of JavaScript logic. Requests for a path the server does not know get a 404, and HTMX does not swap error responses by default. You will handle that in events and headers.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What should the server return to an HTMX request?

    HTMX swaps the response text into the page as HTML, so the server returns just the fragment that should change.
  2. 2. A button has hx-get="/clock" and no hx-target. Where does the reply go?

    Without hx-target the element that issued the request is the target, and the default swap replaces its inner content.
  3. 3. Which header lets a server know a request came from HTMX?

    HTMX adds HX-Request: true to every request it sends.
  4. 4. What does the default swap change?

    The default swap is innerHTML: the target stays, its children are replaced.

Summary

  • HTMX sends a request when an element is triggered and swaps the HTML reply into the page.
  • hx-get chooses the URL; hx-target takes a CSS selector for where the reply goes (default: the element itself).
  • The default swap replaces the target's inner HTML.
  • Every request carries headers such as HX-Request, HX-Target and HX-Trigger, so a server can recognize it.
  • The server returns fragments, and user data in them must be escaped.
  • In this track a small in-page mock server answers requests by method and path.

Next, verbs, triggers and parameters.