Go HTML Views with Gomponents

gomponents

gomponents is HTML components in pure Go. A component is a Go function that returns a Node, and a Node renders itself to an io.Writer as HTML5. There is no template language, no code generation, and no dependencies.

go get maragu.dev/gomponents@latest

Mental model

Everything is a Node:

type Node interface {
	Render(w io.Writer) error
}

Elements, attributes, and text all implement it, and all are passed as children to the same variadic element functions. The result is like a DSL for HTML, in valid Go: an element function takes children, an attribute function takes a value, and nesting calls mirrors nesting tags. Attribute children go in the tag and everything else goes between the tags, whatever order you pass them in; by convention, write attributes first.

<a href="/about" class="nav-link">About</a>

A(Href("/about"), Class("nav-link"), Text("About"))

The idiomatic way is to write it declaratively, but a component is an ordinary function and can be as imperative as it needs to be. gomponents does not check that the result is valid HTML, by design, just as writing HTML by hand doesn't.

The core package provides these functions. Everything else is in the html and components packages.

Element and attribute names are written verbatim, so they must be trusted compile-time values. Attribute values, Text, and Textf are escaped. Never build a name from user input, as in Data(userKey, v) or El(tagFromRequest).

An example component using all of the above except El and Attr:

package html

import (
	. "maragu.dev/gomponents"
	. "maragu.dev/gomponents/components"
	. "maragu.dev/gomponents/html"
)

type NavLink struct {
	Href, Text string
}

type User struct {
	Name   string
	Unread int
}

// Navbar shows the site links and, for a logged-in user, their name and a log out link.
// user is nil for a visitor.
func Navbar(links []NavLink, currentPath string, user *User) Node {
	return Nav(Class("navbar"),
		Map(links, func(l NavLink) Node {
			return A(Href(l.Href), Classes{"link": true, "is-active": l.Href == currentPath}, Text(l.Text))
		}),

		If(user == nil, A(Href("/login"), Text("Log in"))),

		// user.Name must only run when user is not nil.
		Iff(user != nil, func() Node {
			return Group{
				Span(Textf("%v (%v unread)", user.Name, user.Unread)),
				A(Href("/logout"), Text("Log out")),
			}
		}),

		Raw(`<svg viewBox="0 0 16 16" width="16" height="16"><circle cx="8" cy="8" r="7"/></svg>`),
	)
}

Common patterns

• If builds its node before checking the condition. If(user != nil, Text(user.Name)) panics when user is nil, because user.Name runs first. Use Iff when the node reads through a pointer, indexes a slice, or does work worth skipping.
• There is no IfElse. Use two Ifs with opposite conditions, or a function with a switch when the branches are more than one node.
• Map has no index. When you need one, keep a counter in the closure, or use maragu.dev/gomponents/x/slices, whose Map and Filter pass the index and return plain slices to spread with .... Packages under x/ are experimental and may change, although they probably won't.
• Building blocks take children ...Node and pass them on with Group(children). Groups are transparent, so a caller's attributes (ID, Name) are placed on the root element. A block like input(children ...Node) that only adds classes to Input needs no parameters, because callers pass Type("email"), Name("email"), or Required() as children and they land on the input.
• Callers add classes through JoinAttrs. A block joins its own Class with whatever the caller passes, so card(Class("mt-4"), ...) renders one class attribute. See the components package below.
• Dynamic attributes work like dynamic elements, because nil is skipped inside the tag too: If(disabled, Disabled()), Classes{...}, Value(u.Email).
• A fragment is just a component returned without the layout; gomponents has no special notion of it. Return a Group when it has several root elements.
• Print a node to see its HTML. Every built-in node implements fmt.Stringer, so fmt.Println(node) works when debugging.
• <script> and <style> bodies need Raw. Text would turn && into && and break the code. Keep unsanitized user data out of those bodies; pass it through Data attributes instead, which are escaped and unescaped by the browser.
• Two Class calls make two attributes, and the browser keeps only the first. Combine them into one string, use Classes, or use JoinAttrs.
• Void elements silently ignore non-attribute children. Img(Text("x")) renders <img> with no error.

Imports and package layout

Dot-import the three main packages so components read like HTML. This is the strongly preferred style unless the project already imports them another way. Whichever style the project uses, use it in every file that mentions a Node, handler files included: write Node, not g.Node.

Put components in a package named html, unless the project already has one under another name. A package named html can dot-import maragu.dev/gomponents/html without conflict.

Inside that package, export only what another package uses, which is usually just the pages and fragments:

• Exported pages and fragments are named for what they are and take a props struct: func LoginPage(props LoginPageProps) Node, func UserRow(u User) Node.
• Unexported building blocks are camelCase with a lower-case first letter, named after the element they wrap: button, input, label, a, card, container. Names with a lower-case first letter cannot collide with the dot-imported Button, Input, Label, and A. When a block does need exporting, give it a specific name (SubmitButton, not Button) rather than dropping the dot import.

The http package often clashes with net/http, so consider aliasing it: ghttp "maragu.dev/gomponents/http".