text/template & html/template

text/template basics

You parse a template string into a *template.Template, then execute it against a data value, writing the result to any io.Writer. Actions in {{…}} pull from the current data context, written as the dot (.). {{.Field}} reads an exported struct field, a map key, or a zero-argument method:

package main

import (
"os"
"text/template"
)

type Invoice struct {
Customer string
Total    float64
}

func main() {
// Must panics on a parse error — good for templates known at startup.
t := template.Must(template.New("inv").Parse(
	"Dear {{.Customer}}, your total is {{printf \"$%.2f\" .Total}}.\n",
))

t.Execute(os.Stdout, Invoice{Customer: "Ada", Total: 123.456})
// Dear Ada, your total is $123.46.
}

Control flow: if, range, with

Templates have just enough logic to shape output: {{if}}/{{else}} for conditionals, {{range}} to iterate (re-binding the dot to each element), and {{with}} to narrow the dot to a sub-value. There are no arbitrary expressions — that’s deliberate; logic belongs in Go, presentation in the template:

package main

import (
"os"
"text/template"
)

type Cart struct {
User  string
Items []string
}

func main() {
const page = "{{.User}}'s cart:\n" +
	"{{range .Items}}  - {{.}}\n{{else}}  (empty)\n{{end}}" +
	"{{if .Items}}Total items: {{len .Items}}\n{{end}}"

t := template.Must(template.New("cart").Parse(page))

t.Execute(os.Stdout, Cart{User: "Bob", Items: []string{"pen", "ink"}})
t.Execute(os.Stdout, Cart{User: "Cleo"}) // empty cart hits {{else}}
}

Functions and pipelines

A template can call functions. Built-ins include len, printf, index, and comparisons (eq, lt, …). You add your own via a template.FuncMap — attached with .Funcs(...) before parsing, because the parser must recognize the names. The pipeline operator | feeds one result into the next, just like a shell:

package main

import (
"os"
"strings"
"text/template"
)

func main() {
funcs := template.FuncMap{
	"upper": strings.ToUpper,
	"repeat": strings.Repeat,
}

t := template.Must(
	template.New("f").Funcs(funcs).Parse(
		"{{.Name | upper}} {{repeat \"!\" 3}}\n",
	),
)
t.Execute(os.Stdout, map[string]string{"Name": "go"})
// GO !!!
}

html/template: auto-escaping for safety

Switching the import to html/template keeps the identical API but adds the feature that matters for the web: context-aware auto-escaping. The engine tracks whether a value is landing in HTML text, an attribute, a URL, or a <script> block, and escapes it the right way for that spot. This is what stops user input like <script>steal()</script> from becoming executable — the cross-site scripting (XSS) defense you get for free:

package main

import (
"html/template"
"os"
)

func main() {
t := template.Must(template.New("p").Parse(
	"<p>Hello, {{.}}</p>\n",
))

// Hostile input is neutralized automatically.
t.Execute(os.Stdout, "<script>steal()</script>")
// <p>Hello, &lt;script&gt;steal()&lt;/script&gt;</p>

t.Execute(os.Stdout, "Ada & Bob")
// <p>Hello, Ada &amp; Bob</p>
}

The same data through text/template would emit the raw <script> tag verbatim — a live XSS hole. That difference is the whole reason both packages exist.

graph LR
D["data value"] --> T{"which package?"}
T -->|text/template| RAW["bytes emitted verbatim<br/>(reports, configs, code-gen)"]
T -->|html/template| ESC["context-aware escaping<br/>(HTML · attr · JS · URL)"]
ESC --> SAFE["safe HTML — XSS neutralized"]

text/template vs html/template

Under the hood: parse once, execute many

Parsing compiles the template text into an internal tree; executing walks that tree against your data. Parsing is the expensive part, so do it once — at package init or server startup — and execute per request. A *template.Template is safe for concurrent Execute calls once parsed, so one parsed template serves all your goroutines. Real apps usually template.ParseGlob("templates/*.html") to load a whole directory into one template set, then ExecuteTemplate(w, "page.html", data) to render a named one — letting templates {{define}} and {{template}} include each other for layouts.

See also

• encoding/json — the other way to turn Go data into a wire format; both rely on exported fields.
• http-server — render html/template output straight to the http.ResponseWriter.
• strings & bytes — strings.Builder is a handy Execute target when you want a string.
• fmt & io — Execute writes to any io.Writer.

Next: working with dates, durations and timers — time.

Related topics