templ

README

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

Documentation

See user documentation at https://templ.guide

Tasks

nix-develop

Run a Nix shell that contains everything required to build templ.

nix develop --impure

build

Build a local version.

cd cmd/templ
go build

install-snapshot

Build and install to ~/bin

rm cmd/templ/lspcmd/*.txt || true
cd cmd/templ && go build -o ~/bin/templ

build-snapshot

Use goreleaser to build the command line binary using goreleaser.

goreleaser build --snapshot --rm-dist

generate

Run templ generate using local version.

go run ./cmd/templ generate

test

Run Go tests.

go run ./cmd/templ generate && go test ./...

test-cover

Run Go tests.

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

lint

docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:v1.52.2 golangci-lint run -v

release

Create production build with goreleaser.

if [ "${GITHUB_TOKEN}" == "" ]; then echo "No github token, run:"; echo "export GITHUB_TOKEN=`pass github.com/goreleaser_access_token`"; exit 1; fi
./push-tag.sh
goreleaser --clean

docs-run

Run the development server.

Directory: docs

npm run start

docs-build

Build production docs site.

Directory: docs

npm run build

docker-build

Build a Docker container with a full development environment and Neovim setup for testing the LSP.

docker build -t templ:latest .

docker-run

Run a Docker development container in the current directory.

docker run -p 7474:7474 -v `pwd`:/templ -it --rm templ:latest

Documentation

Index

• Constants
• Variables
• func Bool(value bool) bool
• func CSSID(name string, css string) string
• func ClearChildren(ctx context.Context) context.Context
• func EscapeString(s string) string
• func GetBuffer() *bytes.Buffer
• func InitializeContext(ctx context.Context) context.Context
• func ReleaseBuffer(b *bytes.Buffer)
• func RenderCSSItems(ctx context.Context, w io.Writer, classes ...any) (err error)
• func RenderScriptItems(ctx context.Context, w io.Writer, scripts ...ComponentScript) (err error)
• func SafeScript(functionName string, params ...interface{}) string
• func WithChildren(ctx context.Context, children Component) context.Context
• func WithContentType(contentType string) func(*ComponentHandler)
• func WithErrorHandler(eh func(r *http.Request, err error) http.Handler) func(*ComponentHandler)
• func WithStatus(status int) func(*ComponentHandler)
• type CSSClass
  • func Class(name string) CSSClass
  • func SafeClass(name string) CSSClass
• type CSSClasses
  • func Classes(classes ...any) CSSClasses
  • func (classes CSSClasses) String() string
• type CSSHandler
  • func NewCSSHandler(classes ...ComponentCSSClass) CSSHandler
  • func (cssh CSSHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type CSSMiddleware
  • func NewCSSMiddleware(next http.Handler, classes ...ComponentCSSClass) CSSMiddleware
  • func (cssm CSSMiddleware) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Component
  • func GetChildren(ctx context.Context) Component
• type ComponentCSSClass
  • func (css ComponentCSSClass) ClassName() string
• type ComponentFunc
  • func (cf ComponentFunc) Render(ctx context.Context, w io.Writer) error
• type ComponentHandler
  • func Handler(c Component, options ...func(*ComponentHandler)) *ComponentHandler
  • func (ch ComponentHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ComponentScript
• type ConstantCSSClass
  • func (css ConstantCSSClass) ClassName() string
• type KeyValue
  • func KV[TKey comparable, TValue any](key TKey, value TValue) KeyValue[TKey, TValue]
• type SafeCSS
  • func SanitizeCSS(property, value string) SafeCSS
• type SafeURL
  • func URL(s string) SafeURL

Constants

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

FailedSanitizationURL is returned if a URL fails sanitization checks.

Variables

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

NopComponent is a component that doesn't render anything.

var Version string

Binary builds set this version string. goreleaser sets the value using Go build ldflags.

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(s string) string

EscapeString escapes HTML text within templates.

func GetBuffer

func GetBuffer() *bytes.Buffer

func InitializeContext

func InitializeContext(ctx context.Context) context.Context

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

func ReleaseBuffer

func ReleaseBuffer(b *bytes.Buffer)

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 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 ...interface{}) string

SafeScript encodes unknown parameters for safety.

func WithChildren

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

func WithContentType

func WithContentType(contentType string) func(*ComponentHandler)

WithConentType 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 WithStatus

func WithStatus(status int) func(*ComponentHandler)

WithStatus sets the HTTP status code returned by the ComponentHandler.

Types

type CSSClass

type CSSClass interface {
	ClassName() string
}

CSSClass provides a class name.

func Class

func Class(name string) CSSClass

Class returns a sanitized CSS class name.

func SafeClass

func SafeClass(name string) CSSClass

SafeClass bypasses CSS class name validation.

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 ...ComponentCSSClass) 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 ...ComponentCSSClass) 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 GetChildren

func GetChildren(ctx context.Context) Component

GetChildren from the context.

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
}

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.

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.
	// e.g. print({ x: 1 })
	Call string
}

ComponentScript is a templ Script template.

type ConstantCSSClass

type ConstantCSSClass string

ConstantCSSClass is a string constant of a CSS class name.

func (ConstantCSSClass) ClassName

func (css ConstantCSSClass) ClassName() string

ClassName of the CSS class.

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 SafeCSS

type SafeCSS string

SafeCSS is CSS that has been sanitized.

func SanitizeCSS

func SanitizeCSS(property, value string) SafeCSS

SanitizeCSS sanitizes CSS properties to ensure that they are safe.

type SafeURL

type SafeURL string

SafeURL is a URL that has been sanitized.

func URL

func URL(s string) SafeURL

URL sanitizes the input string s and returns a SafeURL.