proposal: render individual template fragments #914

a-h · 2024-09-11T07:25:24Z

a-h
Sep 11, 2024
Maintainer

In this tweet, Carson highlights the capability of Laravel's template engine to render a specific section of an overall template. https://x.com/htmx_org/status/1833450920438272462

This is interesting for HTMX, because with HTMX, you sometimes only want a part of the HTML stream to be returned to the client.

In templ, this could look like:

@Fragment("name") {
  <div>This is a named template fragment.</div>
}

At the moment, you'd have to make a separate templ component for that:

templ named() {
  <div>This is a named template fragment.</div>
}

And then call it - works well, but have to do some refactoring if you're adding this to existing code.

To write out only the fragment without separating the contents into another templ component, the context could be used to trigger the behaviour.

package main

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"slices"
)

type fragmentComponent struct {
	name string
}

func (f fragmentComponent) Render(ctx context.Context, w io.Writer) error {
	// Get children.
	children := templ.GetChildren(ctx)
	ctx = templ.ClearChildren(ctx)
	if children == nil {
		return nil
	}
	// Render children.
	fw, ok := GetFragmentWriter(ctx, f.name)
	if ok {
		w = fw
	}
	return children.Render(ctx, w)
}

type fragmentContextKey struct{}
type fragmentContextValue struct {
	w     io.Writer
	names []string
}

func WithFragment(ctx context.Context, w io.Writer, names ...string) context.Context {
	return context.WithValue(ctx, fragmentContextKey{}, fragmentContextValue{w: w, names: names})
}

func GetFragmentWriter(ctx context.Context, name string) (w io.Writer, ok bool) {
	val, ok := ctx.Value(fragmentContextKey{}).(fragmentContextValue)
	if !ok {
		return nil, false
	}
	if len(val.names) > 0 && !slices.Contains(val.names, name) {
		return nil, false
	}
	return val.w, true
}

func Fragment(name string) templ.Component {
	return fragmentComponent{name: name}
}

templ Page(count int) {
	<!DOCTYPE html>
	<head>
		<title>My Page</title>
		<script src="https://unpkg.com/htmx.org@2.0.2" integrity="sha384-Y7hw+L/jvKeWIRRkqWYfPcvVxHzVzn5REgzbawhxAuQGwX1XWe70vji+VSeHOThJ" crossorigin="anonymous"></script>
	</head>
	<body>
		<h1>My Page</h1>
		<p>This is my page</p>
		@Fragment("count") {
			<div id="count">Count: { fmt.Sprintf("%d", count) }</div>
		}
		<!-- We no longer need to select #count because only the fragment is returned -->
		<button hx-post="/" hx-target="#count">Increment</button>
	</body>
}

func main() {
	var count int
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if r.Method == http.MethodPost {
			count++
		}
		c := Page(count)
		if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
			r = r.WithContext(WithFragment(r.Context(), w, "count"))
			c.Render(r.Context(), io.Discard)
			return
		}
		c.Render(r.Context(), w)
	})

	fmt.Println("Server running on http://127.0.0.1:8080")
	http.ListenAndServe("127.0.0.1:8080", nil)
}

In this example, the GET request returns the whole page:

<!doctype html>
<head>
    <title>My Page</title>
    <script src="https://unpkg.com/htmx.org@2.0.2" integrity="sha384-Y7hw+L/jvKeWIRRkqWYfPcvVxHzVzn5REgzbawhxAuQGwX1XWe70vji+VSeHOThJ" crossorigin="anonymous"></script>
</head>
<body>
    <h1>My Page</h1>
    <p>This is my page</p>
    <div id="count">Count: 0</div>
    <!-- We don't need to select #count because only the fragment is returned -->
    <button hx-post="/" hx-target="#count">Increment</button>
</body>

But the HTMX response returns just the "count" fragment.

<div id="count">Count: 1</div>

I don't like how this design doesn't use the io.Writer that's passed in, using a writer from the context instead, but it does work.

if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
	r = r.WithContext(WithFragment(r.Context(), w, "count"))
	c.Render(r.Context(), io.Discard)
	return
}

That design is partly because that's all that's possible with the current generated code.

templ's generator currently generates code that creates a buffer from the incoming io.Writer, but I'm not sure it should. Maybe this would be better done at the HTTP handler level, and we keep the rendering code really simple.

If we didn't wrap it, we could check (within the Fragment templ component) to see whether the io.Writer is actually a FragmentWriter that only writes the specified fragments and its children, discarding all other writes.

Alternatively, the templ runtime.Buffer type could have this smartness built in.

All of the template is computed, it's simply that only part of the HTML output is returned. I don't think that it's possible (or maybe desirable) to skip computing non-visible parts of the template.

Another design might be even simpler (just pseudocode for now), writing out a comment to start and the fragment.

type fragmentComponent struct {
	id string
	name string
}

func (f fragmentComponent) Render(ctx context.Context, w io.Writer) error {
	// Get children.
	children := templ.GetChildren(ctx)
	ctx = templ.ClearChildren(ctx)
	if children == nil {
		return nil
	}
        // Render prefix.
       io.WriteString(w, "<!-- templ_fragment_start: " + f.id + "-->")
	// Render children.
       err := children.Render(ctx, w)
       io.WriteString(w, "<!-- templ_fragment_end: " + f.id + "-->")
       return err
}

func Fragment(name string) templ.Component {
        id := randomString(name)
	return fragmentComponent{id: id, name: name}
}

templ Page(count int) {
	<!DOCTYPE html>
	<head>
		<title>My Page</title>
		<script src="https://unpkg.com/htmx.org@2.0.2" integrity="sha384-Y7hw+L/jvKeWIRRkqWYfPcvVxHzVzn5REgzbawhxAuQGwX1XWe70vji+VSeHOThJ" crossorigin="anonymous"></script>
	</head>
	<body>
		<h1>My Page</h1>
		<p>This is my page</p>
		@Fragment("count") {
			<div id="count">Count: { fmt.Sprintf("%d", count) }</div>
		}
		<!-- We no longer need to select #count because only the fragment is returned -->
		<button hx-post="/" hx-target="#count">Increment</button>
	</body>
}

Then, a custom writer could discard writes that aren't between the expected comments. templ could provide a custom HTTP response writer too: https://gist.github.com/prakashpandey/f8fe3e8f3d446cd3426ac67ac21172f7

if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
        w := templ.NewResponseWriter(w, WithRenderFragments("count"))
	c.Render(r.Context(), w)
	return
}

I think that implementing some sort of FragmentWriter interface in both the templ buffer, and a templ.ResponseWriter might work.

Thoughts? Worth doing?

joerdav · 2024-09-11T10:27:06Z

joerdav
Sep 11, 2024
Collaborator

I think that the internal implementation you outlined in the first proposed design makes the most sense. I think utilizing context makes sense here too, but I don't think that this fact should be exposed to the user, I would recommend an abstraction here:

func RenderFragment(ctx context.Context, c Component, w io.Writer, name string) error {
	return c.Render(WithFragment(ctx, w, name), io.Discard)
}

This way the dev experience is a bit more intuitive:

http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		if r.Method == http.MethodPost {
			count++
		}
		c := Page(count)
		if r.Method == http.MethodPost && r.Header.Get("HX-Request") == "true" {
			templ.RenderFragment(r.Context(), c, w, "count")
			return
		}
		c.Render(r.Context(), w)
	})

0 replies

Riu · 2024-09-23T22:56:10Z

Riu
Sep 23, 2024

I have another approach. It treats the component (fragment, partial) like an endpoint (/partial/{component-id}, which has its states depending on the HTTP method used. I can return the rendered html by passing data in the template (initial GET state based on URL), or in the endpoint. Example: take a look at how the navigation works in the mobile version for hanariu.dev - there is an animation like in the SPA app (no page reload effect) because it loads the fragment (endpoint) thanks to HTMX.

This has three main advantages for me:

better documentation of the endpoint and business logic of the component;
easier development of isolated components/fragments (potentially good for microfrontends);
reusability;

For small components and changing only data, HTMX alone + e.g. Alpine js is enough.

0 replies

IngwiePhoenix · 2025-02-25T18:27:57Z

IngwiePhoenix
Feb 25, 2025

Was about to write an issue myself and I would really like to weigh in on this, because in my opinion, templ and HTMX go together extremely nicely. For a tiny bit of context, I am visually impaired and try to work as little in the actual frontend as possible, so doing as much as I can in the backend (where I can be far removed from JavaScript land...oofh...the memories x)...) is nice.

I am currently planning a continuation of an old application that I had written in PHP 5.3 and Yii 1.x - that was software from 2012-ish and then some (that is when I discovered git and actually logged stuff, hence why I know). Now these days, htmx and templ can do what PHP back then never could and something React kinda "can't": It can streamline stuff a lot. With htmx, you are just writing HTML and with Templ, you are just calling Go functions that happen to return HTML. React needs JSX, which needs a truckload of additional software and other stuff. Not to hate on it, by the way - I actually enjoy JSX for what it is and what it can do. But the templ + htmx way just seems easier...nicer, even.

One of the most prevalent features of my app back then was creating roleplay characters with detailed showcase pages. But by that point Yii got to render this particular part, it had rendered a menu, a side panel, a footer, some CSS and spliced JavaScript here and there. If something on that character profile changed, the user would have to reload the whole thing. But what if instead it was just tracking some smol stream from the backend that told the user, hey, your character got invited to join this clan/club...I wouldn't want to render any of the other components, and htmx highly discourages it too.

So, for demonstration purposes, let's assume this; any tag with a capital letter is "a thing" and not actually HTML. I am a little lazy here, apologies.

<!DOCTYPE html>
<html>
<head>
    <!-- ... -->
</head>
<body>
    <MenuBar/>
    <Sidebar>
        <UserStatistics/>
        <RecentPosts/>
        <NewsFeed/>
    </Sidebar>
    <div id="content"></div>
    <Footer>
        <Socials/>
        <Copyright/>
        <ProbablyMoreThatIForgot/>
    </Footer>
</body>
</html>

Only #content would have to be refreshed, but we'd be "drilling" down past a lot of components.

Currently, there is one approach I have considered doing but... I will probably just not.

When the request has no HTMX headers, render everything.
If the request HAS HTMX headers, use the info provided via the URL to dig out what is needed.
- If the URL matches the route of the current page but has HTMX headers, just render the entire #content.

This still means that if #content had multiple subelements in it, we'd be redoing those too. Probably not the biggest problem in some cases, but let's say that #content is actually a collection of all the recently posted content from three categories that require different DB data. You would not want to rerender the whole thing if you didn't need to.

"Fragment drilling" would go a long way in my opinion. I am not sure what the best way there is but if I could just write something like

templ Profile(characterId int) {
    @Fragment("profile") {
        @Fragment("bio") {}
        @Fragment("images") {}
    }
    @fragment("relations") {
        @Fragment("invites") {}
        @Fragment("graph") {}
    }
}

...and then just do something like Profile(93).Only("profile.images").Render(...) that would help a lot.
(I know, not all of the above should be a fragment... but, it's just for demonstration purposes.)

Really looking forward if and when this will land because I think htmx and templ can go a long, long way! =)

For the time being I'll just render everything and try to if/else my way out of sticky situations ^^"

0 replies

tinkerbaj · 2025-07-26T18:21:36Z

tinkerbaj
Jul 26, 2025

Is it somehow possible to pass anything to the fragment
for example like in example there is "buttonOnly" fragment
Is it possible to pass for example

@Fragment("buttonOnly", "primary")

2 replies

a-h Jul 26, 2025
Maintainer Author

In templ, you're in a go function, so you can use closures to pass variables, or you can use context to pass values into children.

Some examples of what you're trying to do would help.

joerdav Jul 28, 2025
Collaborator

Usually a fragment is already a part of a larger component that can take certain arguments.

Page1(user).Render(ctx, w)

// Rendering only a fragment requires passing the same args to the page:

templ.RenderFragments(ctx, w, Page1(user), "buttonOnly")

You pass the same parameters, as the component is the same but you are only rendering a fragment of it.

If you want your "Fragment" to have different arguments than the wider page, probably a fragment isn't the correct tool for your scenario!

a-h · 2025-08-01T16:36:05Z

a-h
Aug 1, 2025
Maintainer Author

By the way, this is an old conversation, and I guess I should mention that Fragments were added to templ recently, see https://templ.guide/syntax-and-usage/fragments

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

proposal: render individual template fragments #914

Uh oh!

{{title}}

Uh oh!

Replies: 5 comments 2 replies

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{title}}

Uh oh!

Select a reply

Uh oh!

Uh oh!

proposal: render individual template fragments #914

Uh oh!

a-h Sep 11, 2024 Maintainer

Replies: 5 comments · 2 replies

Uh oh!

joerdav Sep 11, 2024 Collaborator

Uh oh!

Riu Sep 23, 2024

Uh oh!

IngwiePhoenix Feb 25, 2025

Uh oh!

tinkerbaj Jul 26, 2025

Uh oh!

a-h Jul 26, 2025 Maintainer Author

Uh oh!

joerdav Jul 28, 2025 Collaborator

Uh oh!

a-h Aug 1, 2025 Maintainer Author

a-h
Sep 11, 2024
Maintainer

Replies: 5 comments 2 replies

joerdav
Sep 11, 2024
Collaborator

Riu
Sep 23, 2024

IngwiePhoenix
Feb 25, 2025

tinkerbaj
Jul 26, 2025

a-h Jul 26, 2025
Maintainer Author

joerdav Jul 28, 2025
Collaborator

a-h
Aug 1, 2025
Maintainer Author