text/template

text/template parsing and Execute, plus missingkey default, zero, and error options, checked on Go 1.24.0. This package does not auto-escape HTML.

モジュールページの本文は現在英語です。

The text/template package implements data-driven templates for textual output. It is the template language that html/template wraps. This page covers Parse, Execute, and the missingkey option. It does not auto-escape HTML, JavaScript, CSS, or URLs. When the output is HTML, official documentation for html/template says to use that package instead.

The template source must still be trusted. Passing untrusted text to Parse is a different problem from inserting untrusted data during Execute. Examples write to bytes.Buffer and print the result with %q; they are not a served page.

Examples were checked against Go 1.24.0. See the official package documentation for the complete API.

Go reference overview →

API index

APISummary
template.New, Parse, Must, and ExecuteParse a trusted template, then Execute it with data. text/template does not escape HTML.
Template.Option missingkeyThe default missingkey behavior prints <no value> and continues. missingkey=zero uses the element zero value. missingkey=error stops with an error.

Parse and Execute

New and Parse build a template from a trusted string. Execute applies the template to data and writes the result. Actions such as {{.Name}} look up fields or map keys. Must panics if Parse returns an error, which is convenient in examples once the body is known to be valid.

Unlike html/template, a data value that contains <b> or similar markup is inserted unchanged. See the html/template page for the contrast.

template.New, Parse, Must, and Execute

func New(name string) *Template
func Must(t *Template, err error) *Template
func (t *Template) Parse(text string) (*Template, error)
func (t *Template) Execute(wr io.Writer, data any) error

Parse a trusted template, then Execute it with data. text/template does not escape HTML.

ParameterDescription
name, textNew names the template. Parse reads the template body, which must be trusted.
wr, dataExecute writes the result to wr using values from data. Maps and structs are common data types.

Returns: Must returns the template or panics. Execute returns a non-nil error if execution or writing fails.

Errors

  • error — Parse returns a parse error for invalid syntax. This successful example has no execution error.
go
package main

import (
	"bytes"
	"fmt"
	"text/template"
)

func main() {
	t := template.Must(template.New("t").Parse("{{.Name}} has {{.Count}} items."))
	var ok bytes.Buffer
	if err := t.Execute(&ok, map[string]any{"Name": "Ada", "Count": 3}); err != nil {
		fmt.Println(err)
		return
	}
	fmt.Printf("%q\n", ok.String())
}

Expected output

"Ada has 3 items."

Related: html/template, Official text/template

Official documentation →

The missingkey option

Option("missingkey=...") controls what happens when a map is indexed with a key that is not present. Official documentation lists four spellings. missingkey=default and missingkey=invalid are the default: execution continues, and a printed missing key is the string "<no value>". missingkey=zero continues and uses the zero value of the map element type, which for string is the empty string. missingkey=error stops immediately with an error. As with html/template, a failed Execute may already have written a prefix; that case is demonstrated on the html/template page.

Option panics if the option string is unrecognized. The option applies to map index operations, not to every kind of missing field.

Template.Option missingkey

func (t *Template) Option(opt ...string) *Template

The default missingkey behavior prints <no value> and continues. missingkey=zero uses the element zero value. missingkey=error stops with an error.

ParameterDescription
optOne or more option strings. The known missingkey values are default, invalid, zero, and error.

Returns: Option returns the template so calls can be chained. It panics on an unrecognized option.

  • The default template here has no Option call, so a missing key prints <no value> and Execute still returns nil.
go
package main

import (
	"bytes"
	"fmt"
	"text/template"
)

func main() {
	def := template.Must(template.New("d").Parse("value={{.missing}}"))
	zero := template.Must(template.New("z").Option("missingkey=zero").Parse("value={{.missing}}"))
	var a, b bytes.Buffer
	fmt.Println(def.Execute(&a, map[string]string{}))
	fmt.Printf("%q\n", a.String())
	fmt.Println(zero.Execute(&b, map[string]string{}))
	fmt.Printf("%q\n", b.String())
}

Expected output

<nil>
"value=<no value>"
<nil>
"value="

Related: html/template Execute and missingkey=error, Official Option

Official documentation →