Return HTML from the Backend with Astro Partials and htmx

Instructor

Zac Jones

Integrating HTMX with Astro is a straightforward process. We start with a default Astro project and proceed to integrate HTMX.

Adding htmx to Astro

First, we need to include the HTMX script in our project:

  1. Insert HTMX Script Tag: In the layout file, within the <head> section, paste the HTMX script tag. This is crucial for enabling HTMX functionality.

Setting Up an Unordered List with htmx in Astro

Next, we focus on the index.astro page:

  1. Create an Unordered List: Here, we add an <ul> tag.
  2. Configure HTMX Attributes:
    • HX Get: Set to /partials/products/list. This specifies the resource to fetch.
    • HX Trigger: Set to load. This ensures the GET request triggers when the page loads.
<ul hx-get="/partials/products/list" hx-trigger="load"></ul>

Upon initial setup, a 404 error will occur, indicating missing partials:

  1. Create Required Directories and Files: In the file tree, add partials/products folders and a list.astro file.
  2. Configure the List File:
    • Export Const Partial: Set export const partial = true in list.astro. This tells Astro that the file is a partial containing HTML, not a full page.
    • Add List Items: In the template section of list.astro, add several list items (e.g., List 1, List 2, etc.).
export const partial = true;
<li>list 1</li>
<li>list 2</li>
<li>list 3</li>
<li>list 4</li>

With this complete we can see htmx successfully returning a list.

Share with a coworker

Transcript

[00:00] So here I have a default astro project that was created with yarn create astro which generated all these files for me. So the first step to integrating

[00:14] htmx with astro is in the layout. I'm going to go into the head and paste in the htmx script tag. We can head back over to the index dot astro page. And here, I'm going to create an unordered list

[00:33] tag. And in this tag, we are going to have an HX get which will be set to slash partials slash products slash list. And then I will add an HX trigger of load. So when the page loads,

[00:50] this get request is triggered. And you can already see in the console, we're getting a 404 on partials products list. So in my file tree, I'll add folders of partials products, and then a new

[01:05] file of list dot astro. In here to get partials to work, we need to export const partial is equal to true, this is telling astro that this file is not a page, but just some amount of HTML and the

[01:23] HTML that we're going to return here down in the template portion, we're just going to have a number of lists items, we'll say list one, we'll copy this a few times, say two, three, and four. And then when we go back over here, we have list 123 and four loading. And if I look in the console,

[01:42] we can go into the body main, we have this unordered list with the HX get on it and automatically inserted is the four list items that we want to display. And we can go over to

[01:56] the network tab. And if I hit refresh, you can see this list request was sent with a preview, having those list items and the response is just exactly what you would expect HTML,

[02:10] those four list items. So this shows a basic example of astro and HTMX using astro partials. So in review, all we did was in our layout, we added a script tag for HTMX over in our index,

[02:27] we have an empty unordered list that's doing an HX get to our partials slash products slash list route and triggering on the page load over in our list page, we need to export const partial

[02:43] true that tells our astro that when this route is hit, we need to return just a partial amount of HTML, in this case, a short list items, there are some considerations to make here,

[02:58] we're just sending over four list items without any wrapping unordered list. So depending on what your setup is, and your use cases, you might want to return a full unordered list or maybe an ordered

[03:13] list that wraps those list items. But this is HTMX working with astro.