package gomponents

import "maragu.dev/gomponents"

Package gomponents provides HTML components in Go, that render to HTML 5.

The primary interface is a Node. It defines a function Render, which should render the Node to the given writer as a string.

All DOM elements and attributes can be created by using the El and Attr functions.

The functions Text, Textf, Raw, and Rawf can be used to create text nodes, either HTML-escaped or unescaped.

See also helper functions Map, If, and Iff for mapping data to nodes and inserting them conditionally.

There's also the Group type, which is a slice of Node-s that can be rendered as one Node.

For basic HTML elements and attributes, see the package html.

For higher-level HTML components, see the package components.

For HTTP helpers, see the package http.

Index ¶

• Constants
• type Group
• func Map[T any](ts []T, cb func(T) Node) Group
• func (g Group) Render(w io.Writer) error
• func (g Group) String() string
• type Node
• func Attr(name string, value ...string) Node
• func El(name string, children ...Node) Node
• func If(condition bool, n Node) Node
• func Iff(condition bool, f func() Node) Node
• func Raw(t string) Node
• func Rawf(format string, a ...interface{}) Node
• func Text(t string) Node
• func Textf(format string, a ...interface{}) Node
• type NodeFunc
• func (n NodeFunc) Render(w io.Writer) error
• func (n NodeFunc) String() string
• func (n NodeFunc) Type() NodeType
• type NodeType

Examples ¶

• Attr (Bool)
• Attr (Name_value)
• El
• Group
• Group (Slice)
• If
• Iff
• Map
• Map (Index)
• Raw
• Rawf
• Text
• Textf

Constants ¶

const (
	ElementType = NodeType(iota)
	AttributeType
)

Types ¶

type Group ¶

type Group []Node

Group a slice of Node-s into one Node, while still being usable like a regular slice of Node-s. A Group can render directly, but if any of the direct children are AttributeType, they will be ignored, to not produce invalid HTML.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	children := []g.Node{g.El("div"), g.El("span")}
	e := g.Group(children)
	_ = e.Render(os.Stdout)
}

<div></div><span></span>

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.Group{g.El("div"), g.El("span")}
	_ = e.Render(os.Stdout)
}

<div></div><span></span>

func Map ¶

func Map[T any](ts []T, cb func(T) Node) Group

Map a slice of anything to a Group (which is just a slice of Node-s).

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	items := []string{"party hat", "super hat"}
	e := g.El("ul", g.Map(items, func(i string) g.Node {
		return g.El("li", g.Text(i))
	}))
	_ = e.Render(os.Stdout)
}

<ul><li>party hat</li><li>super hat</li></ul>

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	items := []string{"party hat", "super hat"}
	var index int
	e := g.El("ul", g.Map(items, func(i string) g.Node {
		e := g.El("li", g.Textf("%v: %v", index, i))
		index++
		return e
	}))
	_ = e.Render(os.Stdout)
}

<ul><li>0: party hat</li><li>1: super hat</li></ul>

func (Group) Render ¶

func (g Group) Render(w io.Writer) error

Render satisfies Node.

func (Group) String ¶

func (g Group) String() string

String satisfies fmt.Stringer.

type Node ¶

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

Node is a DOM node that can Render itself to a io.Writer.

func Attr ¶

func Attr(name string, value ...string) Node

Attr creates an attribute DOM Node with a name and optional value. If only a name is passed, it's a name-only (boolean) attribute (like "required"). If a name and value are passed, it's a name-value attribute (like `class="header"`). More than one value make Attr panic. Use this if no convenience creator exists in the html package.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("input", g.Attr("required"))
	_ = e.Render(os.Stdout)
}

<input required>

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("div", g.Attr("id", "hat"))
	_ = e.Render(os.Stdout)
}

<div id="hat"></div>

func El ¶

func El(name string, children ...Node) Node

El creates an element DOM Node with a name and child Nodes. See https://dev.w3.org/html5/spec-LC/syntax.html#elements-0 for how elements are rendered. No tags are ever omitted from normal tags, even though it's allowed for elements given at https://dev.w3.org/html5/spec-LC/syntax.html#optional-tags If an element is a void element, non-attribute children nodes are ignored. Use this if no convenience creator exists in the html package.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("div", g.El("span"))
	_ = e.Render(os.Stdout)
}

<div><span></span></div>

func If ¶

func If(condition bool, n Node) Node

If condition is true, return the given Node. Otherwise, return nil. This helper function is good for inlining elements conditionally. If it's important that the given Node is only evaluated if condition is true (for example, when using nilable variables), use Iff instead.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	showMessage := true

	e := g.El("div",
		g.If(showMessage, g.El("span", g.Text("You lost your hat!"))),
		g.If(!showMessage, g.El("span", g.Text("No messages."))),
	)

	_ = e.Render(os.Stdout)
}

<div><span>You lost your hat!</span></div>

func Iff ¶

func Iff(condition bool, f func() Node) Node

Iff condition is true, call the given function. Otherwise, return nil. This helper function is good for inlining elements conditionally when the node depends on nilable data, or some other code that could potentially panic. If you just need simple conditional rendering, see If.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	type User struct {
		Name string
	}
	var user *User

	e := g.El("div",
		// This would panic using just If
		g.Iff(user != nil, func() g.Node {
			return g.Text(user.Name)
		}),
	)

	_ = e.Render(os.Stdout)
}

<div></div>

func Raw ¶

func Raw(t string) Node

Raw creates a text DOM Node that just Renders the unescaped string t.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("span",
		g.Raw(`<button onclick="javascript:alert('Party time!')">Party hats</button> &gt; normal hats.`),
	)
	_ = e.Render(os.Stdout)
}

<span><button onclick="javascript:alert('Party time!')">Party hats</button> &gt; normal hats.</span>

func Rawf ¶

func Rawf(format string, a ...interface{}) Node

Rawf creates a text DOM Node that just Renders the interpolated and unescaped string format.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("span",
		g.Rawf(`<button onclick="javascript:alert('%v')">Party hats</button> &gt; normal hats.`, "Party time!"),
	)
	_ = e.Render(os.Stdout)
}

<span><button onclick="javascript:alert('Party time!')">Party hats</button> &gt; normal hats.</span>

func Text ¶

func Text(t string) Node

Text creates a text DOM Node that Renders the escaped string t.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("span", g.Text("Party hats > normal hats."))
	_ = e.Render(os.Stdout)
}

<span>Party hats &gt; normal hats.</span>

func Textf ¶

func Textf(format string, a ...interface{}) Node

Textf creates a text DOM Node that Renders the interpolated and escaped string format.

package main

import (
	"os"

	g "maragu.dev/gomponents"
)

func main() {
	e := g.El("span", g.Textf("%v party hats > %v normal hats.", 2, 3))
	_ = e.Render(os.Stdout)
}

<span>2 party hats &gt; 3 normal hats.</span>

type NodeFunc ¶

type NodeFunc func(io.Writer) error

NodeFunc is a render function that is also a Node of ElementType.

func (NodeFunc) Render ¶

func (n NodeFunc) Render(w io.Writer) error

Render satisfies Node.

func (NodeFunc) String ¶

func (n NodeFunc) String() string

String satisfies fmt.Stringer.

func (NodeFunc) Type ¶

func (n NodeFunc) Type() NodeType

Type satisfies nodeTypeDescriber.

type NodeType ¶

type NodeType int

NodeType describes what type of Node it is, currently either an ElementType or an AttributeType. This decides where a Node should be rendered. Nodes default to being ElementType.

Source Files ¶

gomponents.go

Directories ¶