Documentation
¶
Overview ¶
Package templ provides a format.Format factory that renders a github.com/a-h/templ component as a text/html response.
Use Format to create a templ format and add it to the ResponseFormats of a [rest.Route]. The existing adapters/nethttp and adapters/chi adapters handle content negotiation: browsers that send Accept: text/html receive the rendered component; API clients that send Accept: application/json receive JSON — all from the same handler and the same route definition.
route, _ := rest.NewRoute[Req, Props]("GET", "/articles", reqCodec, propsCodec,
rest.RouteMeta{},
adapttempl.Format(propsCodec, ArticleList), // Accept: text/html
format.JSON(propsCodec), // Accept: application/json
).Register(b)
// Same handler, same route — nethttp handles both formats:
nethttp.Register(mux, route, func(ctx context.Context, req SearchReq) (Props, error) {
return svc.Search(ctx, req.Query)
}, nethttp.Options{Observer: obs})
Props are validated via the route's response codec before the component renders. Invalid props return HTTP 500 and the template is never reached.
The templ component receives context.Background during rendering; data needed by the component should be included in the Props struct.
For chi routers, use adapters/chi with the same route and add the format via ResponseFormats — no chi-specific variant is needed.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Format ¶
func Format[Props any](c codex.Codec[Props], component func(Props) atempl.Component) format.Format[Props]
Format wraps a templ component as a format.Format with ContentType "text/html; charset=utf-8". Add it to a route's ResponseFormats to enable HTML rendering via the existing adapters/nethttp or adapters/chi adapters.
Props are validated via c (all Refine constraints run) before the component renders. If validation fails, the adapter returns HTTP 500 before any HTML is written.
The component is rendered with context.Background. Pass all data the component needs through the Props struct.
The response is fully buffered — the rendered HTML is held in memory before the response is written. Use StreamingFormat to render directly to the response writer without buffering.
func StreamingFormat ¶
func StreamingFormat[Props any](c codex.Codec[Props], component func(Props) atempl.Component) format.Format[Props]
StreamingFormat wraps a templ component as a streaming format.Format with ContentType "text/html; charset=utf-8". Unlike Format, the component renders directly to the [http.ResponseWriter] without buffering to a []byte intermediate — ideal for large HTML pages.
Props are validated via c (all Refine constraints run) before the component renders; validation errors are caught before response headers are committed. If rendering fails after headers are written, the client receives a truncated response.
The component is rendered with context.Background. Pass all data the component needs through the Props struct.
Types ¶
type DecodeNotSupportedError ¶
type DecodeNotSupportedError struct {
// ContentType is the content type of the response that cannot be decoded.
ContentType string
}
DecodeNotSupportedError is returned by the templ format's Unmarshal function. HTML responses cannot be decoded back into a typed value. Use errors.As to detect this error when inspecting format decode failures.
func (DecodeNotSupportedError) Error ¶
func (e DecodeNotSupportedError) Error() string
Source Files