gomponents

gomponents is a library for generating HTML in Go using a type-safe, programmatic approach instead of traditional template languages. It is designed for scenarios requiring high performance and Go's native type safety, such as:

• Server-side rendered (SSR) web applications
• API servers returning HTML
• Static site generators
• Email template generation
• Any programmatic HTML generation needs

gomponents allows you to build HTML components using pure Go functions. Instead of using template files, you write Go code that produces type-safe HTML5 output.

The Node Interface

The fundamental building block is the Node interface. Everything in the library—elements, attributes, text, and components—implements this interface:

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

Node Types

• ElementType: Represents regular HTML elements (like div, span) and text nodes.
• AttributeType: Represents HTML attributes (like class, href).

The library automatically manages the correct placement of these types during the rendering process.

The library is organized into several specialized packages:

• gomponents: The core package containing fundamental interfaces and functions like Node, El, Attr, and helpers like Map, Group, If, Text, and Raw.
• gomponents/html: Contains standard HTML elements and attributes.
• gomponents/components: Provides higher-level, reusable components and utilities.
• gomponents/http: Contains utilities specifically for use with web servers.
• gomponents/x/...: Experimental packages. Warning: These do not have the same compatibility guarantees as the core library and may introduce breaking changes.

In gomponents, there is a deliberate design decision regarding how HTML elements and attributes are rendered:

• Attribute Values: These are automatically escaped using template.HTMLEscapeString to prevent injection.
• Element and Attribute Names: These are rendered verbatim (unescaped).

Security Warning: Because names are rendered unescaped, they are treated as trusted structural input. Never use user-controlled data as an element name or an attribute name, as this allows an attacker to inject arbitrary attributes or whitespace into the HTML structure.

This contract applies to the following core functions and helpers:

• El (element creation)
• Attr (attribute creation)
• html.Aria (ARIA attribute helper)
• html.Data (Data attribute helper)
• components.JoinAttrs (Attribute joining helper)

A significant performance optimization in gomponents involves how attributes are handled to reduce heap allocations.

Previously, the Attr(name string, value ...string) function captured the entire variadic []string slice into its closure. Because the slice was captured, it escaped to the heap.

To optimize this, the library now internally dispatches to specialized functions (booleanAttr or valueAttr) that extract the scalar string values from the variadic slice before creating the closure. This allows the Go compiler's escape analysis to see that the slice does not escape, significantly reducing the number of allocations per element.

Impact: This change reduces allocations by approximately 23-25% and improves ns/op by ~7-8% in realistic workloads without changing the public API.

You can integrate gomponents into your web server by using the Adapt() function from the maragu.dev/gomponents/http package. This converts a function that returns (Node, error) into a standard http.HandlerFunc.

import (
    "net/http"
    
    . "maragu.dev/gomponents"
    . "maragu.dev/gomponents/html"
    ghttp "maragu.dev/gomponents/http"
)

func HomeHandler(w http.ResponseWriter, r *http.Request) (Node, error) {
    return Div(Text("Welcome!")), nil
}

// In main:
http.HandleFunc("/", ghttp.Adapt(HomeHandler))

Depending on your preference for code readability versus standard Go idioms, you can use two different import patterns.

Dot imports (Recommended)

Dot imports are recommended because they allow the Go code to read like an HTML DSL (Domain Specific Language), making the component structure highly readable.

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

Standard imports with aliases (Alternative)

If you prefer to avoid dot imports, use single-letter aliases to keep the code concise.

import (
    g "maragu.dev/gomponents"
    h "maragu.dev/gomponents/html"
    c "maragu.dev/gomponents/components"
    ghttp "maragu.dev/gomponents/http"
)

To use gomponents in your Go project, install it using go get:

go get maragu.dev/gomponents

A Group is a slice of Nodes that can be treated as a single Node.

Behavioral Nuance: When a Group is rendered as a child of an element (via El), it only renders nodes of type ElementType. If a Group contains AttributeType nodes, those attributes will be ignored during the rendering of the group as children to prevent invalid HTML. This makes Group ideal for collecting both attributes and children in a single slice, which you can then pass to El.