templ

package module
v0.0.0-...-5e9b5be Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 7, 2026 License: MIT Imports: 24 Imported by: 0

README

templ

An HTML templating language for Go that has great developer tooling.

templ

Documentation

See user documentation at https://templ.guide

Go Reference xc compatible Go Coverage Go Report Card

Tasks

version-set

Set the version of templ to the current version.

version set --template="0.3.%d"

build

Build a local version.

version set --template="0.3.%d"
cd cmd/templ
go build

install-snapshot

Build and install current version.

# Remove templ from the non-standard ~/bin/templ path
# that this command previously used.
rm -f ~/bin/templ
# Clear LSP logs.
rm -f cmd/templ/lspcmd/*.txt
# Update version.
version set --template="0.3.%d"
# Install to $GOPATH/bin or $HOME/go/bin
cd cmd/templ && go install

build-snapshot

Use goreleaser to build the command line binary using goreleaser.

goreleaser build --snapshot --clean

generate

Run templ generate using local version.

go run ./cmd/templ generate -include-version=false

test

Run Go tests.

version set --template="0.3.%d"
go run ./cmd/templ generate -include-version=false
go test ./...

test-short

Run Go tests.

version set --template="0.3.%d"
go run ./cmd/templ generate -include-version=false
go test ./... -short

test-cover

Run Go tests.

# Create test profile directories.
mkdir -p coverage/fmt
mkdir -p coverage/generate
mkdir -p coverage/version
mkdir -p coverage/unit
# Build the test binary.
go build -cover -o ./coverage/templ-cover ./cmd/templ
# Run the covered generate command.
GOCOVERDIR=coverage/fmt ./coverage/templ-cover fmt .
GOCOVERDIR=coverage/generate ./coverage/templ-cover generate -include-version=false
GOCOVERDIR=coverage/version ./coverage/templ-cover version
# Run the unit tests.
go test -cover ./... -coverpkg ./... -args -test.gocoverdir="$PWD/coverage/unit"
# Display the combined percentage.
go tool covdata percent -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit
# Generate a text coverage profile for tooling to use.
go tool covdata textfmt -i=./coverage/fmt,./coverage/generate,./coverage/version,./coverage/unit -o coverage.out
# Print total
go tool cover -func coverage.out | grep total

test-cover-watch

interactive: true

gotestsum --watch -- -coverprofile=coverage.out

test-fuzz

./parser/v2/fuzz.sh
./parser/v2/goexpression/fuzz.sh

benchmark

Run benchmarks.

go run ./cmd/templ generate -include-version=false && go test ./... -bench=. -benchmem

fmt

Format all Go and templ code.

gofmt -s -w .
go run ./cmd/templ fmt .

lint

Run the lint operations that are run as part of the CI.

golangci-lint run --verbose

ensure-generated

Ensure that templ files have been generated with the local version of templ, and that those files have been added to git.

Requires: generate

git diff --exit-code

push-release-tag

Push a semantic version number to GitHub to trigger the release process.

version push --template="0.3.%d" --prefix="v"

docs-run

Run the development server.

Directory: docs

npm run start

docs-build

Build production docs site.

Directory: docs

npm run build

Documentation

Index

Constants

View Source 
const FailedSanitizationURL = SafeURL("about:invalid#TemplFailedSanitizationURL")

FailedSanitizationURL is returned if a URL fails sanitization checks.

Variables

View Source 
var NopComponent = ComponentFunc(func(ctx context.Context, w io.Writer) error { return nil })

NopComponent is a component that doesn't render anything.

Functions

func Bool 

func Bool(value bool) bool

Bool attribute value.

func CSSID 

func CSSID(name string, css string) string

CSSID calculates an ID.

func ClearChildren 

func ClearChildren(ctx context.Context) context.Context

func EscapeString 

func EscapeString[T ~string](s T) string

EscapeString escapes HTML text within templates.

func GetBuffer 

func GetBuffer() *bytes.Buffer

func GetNonce 

func GetNonce(ctx context.Context) (nonce string)

GetNonce returns the CSP nonce value set with WithNonce, or an empty string if none has been set.

func InitializeContext 

func InitializeContext(ctx context.Context) context.Context

InitializeContext initializes context used to store internal state used during rendering.

func JSONString 

func JSONString(v any) (string, error)

JSONString returns a JSON encoded string of v.

func JoinStringErrs 

func JoinStringErrs[T stringable](s T, errs ...error) (string, error)

JoinStringErrs joins an optional list of errors.

func ReleaseBuffer 

func ReleaseBuffer(b *bytes.Buffer)

func RenderAttributes 

func RenderAttributes(ctx context.Context, w io.Writer, attributes Attributer) (err error)

func RenderCSSItems 

func RenderCSSItems(ctx context.Context, w io.Writer, classes ...any) (err error)

RenderCSSItems renders the CSS to the writer, if the items haven't already been rendered.

func RenderFragments 

func RenderFragments(ctx context.Context, w io.Writer, c Component, ids ...any) error

RenderFragments renders the specified fragments to w.

func RenderScriptItems 

func RenderScriptItems(ctx context.Context, w io.Writer, scripts ...ComponentScript) (err error)

RenderScriptItems renders a <script> element, if the script has not already been rendered.

func SafeScript 

func SafeScript(functionName string, params ...any) string

SafeScript encodes unknown parameters for safety for inside HTML attributes.

func SafeScriptInline 

func SafeScriptInline(functionName string, params ...any) string

SafeScript encodes unknown parameters for safety for inline scripts.

func ToGoHTML 

func ToGoHTML(ctx context.Context, c Component) (s template.HTML, err error)

ToGoHTML renders the component to a Go html/template template.HTML string.

func Version 

func Version() string

func WithChildren 

func WithChildren(ctx context.Context, children Component) context.Context

func WithContentType 

func WithContentType(contentType string) func(*ComponentHandler)

WithContentType sets the Content-Type header returned by the ComponentHandler.

func WithErrorHandler 

func WithErrorHandler(eh func(r *http.Request, err error) http.Handler) func(*ComponentHandler)

WithErrorHandler sets the error handler used if rendering fails.

func WithFragments 

func WithFragments(ids ...any) func(*ComponentHandler)

WithFragments sets the ids of the fragments to render. If not set, all content is rendered.

func WithNonce 

func WithNonce(ctx context.Context, nonce string) context.Context

WithNonce sets a CSP nonce on the context and returns it.

func WithStatus 

func WithStatus(status int) func(*ComponentHandler)

WithStatus sets the HTTP status code returned by the ComponentHandler.

func WithStreaming 

func WithStreaming() func(*ComponentHandler)

WithStreaming sets the ComponentHandler to stream the response instead of buffering it.

func WriteWatchModeString deprecated 

func WriteWatchModeString(w io.Writer, lineNum int) error

WriteWatchModeString is used when rendering templates in development mode. the generator would have written non-go code to the _templ.txt file, which is then read by this function and written to the output.

Deprecated: since templ v0.3.x generated code uses WriteString.

Types

type Attributer 

type Attributer interface {
	Items() []KeyValue[string, any]
}

type Attributes 

type Attributes map[string]any

Attributes is an alias to map[string]any made for spread attributes.

func (Attributes) Items 

func (a Attributes) Items() []KeyValue[string, any]

Returns the items of the attributes map in key sorted order.

type CSSClass 

type CSSClass interface {
	ClassName() string
}

CSSClass provides a class name.

func Class 

func Class(name string) CSSClass

Class returns a CSS class name. Deprecated: use a string instead.

func SafeClass 

func SafeClass(name string) CSSClass

SafeClass bypasses CSS class name validation. Deprecated: use a string instead.

type CSSClasses 

type CSSClasses []any

CSSClasses is a slice of CSS classes.

func Classes 

func Classes(classes ...any) CSSClasses

Classes for CSS. Supported types are string, ConstantCSSClass, ComponentCSSClass, map[string]bool.

func (CSSClasses) String 

func (classes CSSClasses) String() string

String returns the names of all CSS classes.

type CSSHandler 

type CSSHandler struct {
	Logger  func(err error)
	Classes []ComponentCSSClass
}

CSSHandler is a HTTP handler that serves CSS.

func NewCSSHandler 

func NewCSSHandler(classes ...CSSClass) CSSHandler

NewCSSHandler creates a handler that serves a stylesheet containing the CSS of the classes passed in. This is used by the CSSMiddleware to provide global stylesheets for templ components.

func (CSSHandler) ServeHTTP 

func (cssh CSSHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type CSSMiddleware 

type CSSMiddleware struct {
	Path       string
	CSSHandler CSSHandler
	Next       http.Handler
}

CSSMiddleware renders a global stylesheet.

func NewCSSMiddleware 

func NewCSSMiddleware(next http.Handler, classes ...CSSClass) CSSMiddleware

NewCSSMiddleware creates HTTP middleware that renders a global stylesheet of ComponentCSSClass CSS if the request path matches, or updates the HTTP context to ensure that any handlers that use templ.Components skip rendering <style> elements for classes that are included in the global stylesheet. By default, the stylesheet path is /styles/templ.css

func (CSSMiddleware) ServeHTTP 

func (cssm CSSMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Component 

type Component interface {
	// Render the template.
	Render(ctx context.Context, w io.Writer) error
}

Component is the interface that all templates implement.

func Fragment 

func Fragment(id any) Component

Fragment defines a fragment within a template that can be rendered conditionally based on the id. You can use it to render a specific part of a page, e.g. to reduce the amount of HTML returned from a htmx-initiated request. Any non-matching contents of the template are rendered, but discarded by the FramentWriter.

func FromGoHTML 

func FromGoHTML(t *template.Template, data any) Component

FromGoHTML creates a templ Component from a Go html/template template.

func GetChildren 

func GetChildren(ctx context.Context) Component

GetChildren from the context.

func Join 

func Join(components ...Component) Component

Join returns a single `templ.Component` that will render provided components in order. If any of the components return an error the Join component will immediately return with the error.

func Raw 

func Raw[T ~string](html T, errs ...error) Component

Raw renders the input HTML to the output without applying HTML escaping.

Use of this component presents a security risk - the HTML should come from a trusted source, because it will be included as-is in the output.

type ComponentCSSClass 

type ComponentCSSClass struct {
	// ID of the class, will be autogenerated.
	ID string
	// Definition of the CSS.
	Class SafeCSS
}

ComponentCSSClass is a templ.CSS

func (ComponentCSSClass) ClassName 

func (css ComponentCSSClass) ClassName() string

ClassName of the CSS class.

type ComponentFunc 

type ComponentFunc func(ctx context.Context, w io.Writer) error

ComponentFunc converts a function that matches the Component interface's Render method into a Component.

func (ComponentFunc) Render 

func (cf ComponentFunc) Render(ctx context.Context, w io.Writer) error

Render the template.

type ComponentHandler 

type ComponentHandler struct {
	Component      Component
	Status         int
	ContentType    string
	ErrorHandler   func(r *http.Request, err error) http.Handler
	StreamResponse bool
	FragmentIDs    []any
}

ComponentHandler is a http.Handler that renders components.

func Handler 

func Handler(c Component, options ...func(*ComponentHandler)) *ComponentHandler

Handler creates a http.Handler that renders the template.

func (ComponentHandler) ServeHTTP 

func (ch ComponentHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP implements the http.Handler interface.

func (*ComponentHandler) ServeHTTPBuffered 

func (ch *ComponentHandler) ServeHTTPBuffered(w http.ResponseWriter, r *http.Request)

func (*ComponentHandler) ServeHTTPBufferedComplete 

func (ch *ComponentHandler) ServeHTTPBufferedComplete(w http.ResponseWriter, r *http.Request)

func (*ComponentHandler) ServeHTTPBufferedFragment 

func (ch *ComponentHandler) ServeHTTPBufferedFragment(w http.ResponseWriter, r *http.Request)

func (*ComponentHandler) ServeHTTPStreamed 

func (ch *ComponentHandler) ServeHTTPStreamed(w http.ResponseWriter, r *http.Request)

type ComponentScript 

type ComponentScript struct {
	// Name of the script, e.g. print.
	Name string
	// Function to render.
	Function string
	// Call of the function in JavaScript syntax, including parameters, and
	// ensures parameters are HTML escaped; useful for injecting into HTML
	// attributes like onclick, onhover, etc.
	//
	// Given:
	//    functionName("some string",12345)
	// It would render:
	//    __templ_functionName_sha(&#34;some string&#34;,12345))
	//
	// This is can be injected into HTML attributes:
	//    <button onClick="__templ_functionName_sha(&#34;some string&#34;,12345))">Click Me</button>
	Call string
	// Call of the function in JavaScript syntax, including parameters. It
	// does not HTML escape parameters; useful for directly calling in script
	// elements.
	//
	// Given:
	//    functionName("some string",12345)
	// It would render:
	//    __templ_functionName_sha("some string",12345))
	//
	// This is can be used to call the function inside a script tag:
	//    <script>__templ_functionName_sha("some string",12345))</script>
	CallInline string
}

ComponentScript is a templ Script template.

func JSFuncCall 

func JSFuncCall[T ~string](functionName T, args ...any) ComponentScript

JSFuncCall calls a JavaScript function with the given arguments.

It can be used in event handlers, e.g. onclick, onhover, etc. or directly in HTML.

func JSUnsafeFuncCall 

func JSUnsafeFuncCall[T ~string](js T) ComponentScript

JSUnsafeFuncCall calls arbitrary JavaScript in the js parameter.

Use of this function presents a security risk - the JavaScript must come from a trusted source, because it will be included as-is in the output.

func (ComponentScript) Render 

func (c ComponentScript) Render(ctx context.Context, w io.Writer) error

type ConstantCSSClass 

type ConstantCSSClass string

ConstantCSSClass is a string constant of a CSS class name. Deprecated: use a string instead.

func (ConstantCSSClass) ClassName 

func (css ConstantCSSClass) ClassName() string

ClassName of the CSS class.

type Error 

type Error struct {
	Err error
	// FileName of the template file.
	FileName string
	// Line index of the error.
	Line int
	// Col index of the error.
	Col int
}

Error returned during template rendering.

func (Error) Error 

func (e Error) Error() string

func (Error) Unwrap 

func (e Error) Unwrap() error

type FlushComponent 

type FlushComponent struct {
}

func Flush 

func Flush() FlushComponent

Flush flushes the output buffer after all its child components have been rendered.

func (FlushComponent) Render 

func (f FlushComponent) Render(ctx context.Context, w io.Writer) (err error)

type FragmentContext 

type FragmentContext struct {
	W      io.Writer
	IDs    []any
	Active bool
}

FragmentContext is used to control rendering of fragments within a template.

type JSExpression 

type JSExpression string

JSExpression represents a JavaScript expression intended for use as an argument for script templates. The string value of JSExpression will be inserted directly as JavaScript code in function call arguments.

type JSONScriptElement 

type JSONScriptElement struct {
	// ID of the element in the DOM.
	ID string
	// Type of the script element, defaults to "application/json".
	Type string
	// Data that will be encoded as JSON.
	Data any
	// Nonce is a function that returns a CSP nonce.
	// Defaults to CSPNonceFromContext.
	// See https://content-security-policy.com/nonce for more information.
	Nonce func(ctx context.Context) string
}

func JSONScript 

func JSONScript(id string, data any) JSONScriptElement

JSONScript renders a JSON object inside a script element. e.g. <script type="application/json">{"foo":"bar"}</script>

func (JSONScriptElement) Render 

func (j JSONScriptElement) Render(ctx context.Context, w io.Writer) (err error)

func (JSONScriptElement) WithNonceFrom 

func (j JSONScriptElement) WithNonceFrom(f func(context.Context) string) JSONScriptElement

WithNonceFrom sets the value of the nonce attribute of the script element to the value returned by the given function.

func (JSONScriptElement) WithNonceFromString 

func (j JSONScriptElement) WithNonceFromString(nonce string) JSONScriptElement

WithNonceFromString sets the value of the nonce attribute of the script element to the given string.

func (JSONScriptElement) WithType 

func (j JSONScriptElement) WithType(t string) JSONScriptElement

WithType sets the value of the type attribute of the script element.

type KeyValue 

type KeyValue[TKey comparable, TValue any] struct {
	Key   TKey   `json:"name"`
	Value TValue `json:"value"`
}

KeyValue is a key and value pair.

func KV 

func KV[TKey comparable, TValue any](key TKey, value TValue) KeyValue[TKey, TValue]

KV creates a new key/value pair from the input key and value.

type OnceHandle 

type OnceHandle struct {
	// contains filtered or unexported fields
}

OnceHandle is used to ensure that the children of its `Once` method are are only rendered once per context.

func NewOnceHandle 

func NewOnceHandle(opts ...OnceOpt) *OnceHandle

NewOnceHandle creates a OnceHandle used to ensure that the children of its `Once` method are only rendered once per context.

func (*OnceHandle) Once 

func (o *OnceHandle) Once() Component

Once returns a component that renders its children once per context.

type OnceOpt 

type OnceOpt func(*OnceHandle)

func WithComponent 

func WithComponent(c Component) OnceOpt

WithOnceComponent sets the component to be rendered once per context. This can be used instead of setting the children of the `Once` method, for example, if creating a code component outside of a templ HTML template.

type OrderedAttributes 

type OrderedAttributes []KeyValue[string, any]

OrderedAttributes stores attributes in order of insertion.

func (OrderedAttributes) Items 

func (a OrderedAttributes) Items() []KeyValue[string, any]

type SafeCSS 

type SafeCSS string

SafeCSS is CSS that has been sanitized.

func SanitizeCSS 

func SanitizeCSS[T ~string](property string, value T) SafeCSS

SanitizeCSS sanitizes CSS properties to ensure that they are safe.

type SafeCSSProperty 

type SafeCSSProperty string

type SafeURL 

type SafeURL string

SafeURL is a URL that has been sanitized.

func JoinURLErrs 

func JoinURLErrs[T ~string](s T, errs ...error) (SafeURL, error)

JoinURLErrs joins an optional list of errors and returns a sanitized SafeURL.

func URL 

func URL(s string) SafeURL

URL sanitizes the input string s and returns a SafeURL.

Source Files

View all Source files

Directories

Path Synopsis
benchmarks
templ
This package is inspired by the GOEXPERIMENT approach of allowing feature flags for experimenting with breaking changes.
 This package is inspired by the GOEXPERIMENT approach of allowing feature flags for experimenting with breaking changes.
cmd
templ command
templ/fmtcmd
templ/generatecmd
templ/generatecmd/modcheck
templ/generatecmd/proxy
templ/generatecmd/run
templ/generatecmd/run/testprogram command
templ/generatecmd/sse
templ/generatecmd/watcher
templ/infocmd
templ/lspcmd
templ/lspcmd/httpdebug
templ/lspcmd/lspdiff
templ/lspcmd/pls
templ/lspcmd/proxy
templ/processor
templ/sloghandler
templ/testproject
templ/visualize
examples
content-security-policy command
hello-world-ssr command
hello-world-static command
syntax-and-usage/components command
htmldiff
test-a-href
test-attribute-errors
test-attribute-escaping
test-call
test-cancelled-context
test-class-whitespace
test-complex-attributes
test-constant-attribute-escaping
test-context
test-css-expression
test-css-middleware
test-css-usage
test-doctype
test-doctype-html4
test-element-attributes
test-elseif
test-for
test-form-action
test-fragment
test-go-comments
test-go-template-in-templ
test-html
test-html-comment
test-if
test-ifelse
test-import
test-js-unsafe-usage
test-js-usage
test-method
test-once
test-only-scripts
test-primitives
test-raw-elements
test-script-expressions
test-script-inline
test-script-usage
test-script-usage-nonce
test-spread-attributes
test-string
test-string-errors
test-style-attribute
test-switch
test-switchdefault
test-templ-element
test-templ-in-go-template
test-text
test-text-whitespace
test-void
test-whitespace-around-go-keywords
internal
format
htmlfind
imports
lazyloader
prettier
skipdir
syncmap
syncset
lsp
jsonrpc2
Package jsonrpc2 is an implementation of the JSON-RPC 2 specification for Go.
 Package jsonrpc2 is an implementation of the JSON-RPC 2 specification for Go.
protocol
Package protocol implements Language Server Protocol specification in Go.
 Package protocol implements Language Server Protocol specification in Go.
uri
xcontext
Package xcontext is a package to offer the extra functionality we need from contexts that is not available from the standard context package.
 Package xcontext is a package to offer the extra functionality we need from contexts that is not available from the standard context package.
parser
v2
v2/goexpression
v2/visitor

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.