gsx

name	gsx
description	Use when writing or editing .gsx files — gsx templating components, JSX-style markup in Go, or when asked about gsx syntax (component declarations, interpolation, attributes, control flow, class/style, children/fallthrough).

Authoring gsx templates

gsx is a Go templating language: templ-style component declarations with a JSX-style markup body, compiled to plain Go (.gsx → .x.go).

Status: gsx is runnable — gsx generate compiles .gsx → .x.go. The language is stable but still evolving (some CLI commands and style composition are in progress). Treat the internal/corpus/testdata/cases/**/*.txtar corpus as the canonical, current reference — each case pins the .gsx input, generated Go, and rendered output — and prefer copying patterns from there.

Core rules

• A .gsx file is ordinary Go (package, imports, types, funcs) plus component declarations. Put non-template Go (helpers, types) in the same file as normal Go.
• A component body is emission — the markup is the result. No return type, no return keyword. Bare Go statements are not allowed in the body; wrap them in {{ … }}.
• Capitalization decides the tag's meaning: lowercase/hyphenated → HTML element (<div>, <el-dialog>); Capitalized/dotted → component (<Card>, <ui.Button>).
• A component's authored parameter list is emitted unchanged. Markup binds ordinary parameters by exact name; direct Go callers use the same positional signature. For component Card(title string, featured bool), <Card title="Hi" featured/> binds title and featured, while Go calls Card("Hi", true).
• Lowercase children and attrs are reserved roles only when declared as parameters. children receives the markup body. attrs receives unmatched attributes and ordered bag contributors such as attrs={bag} and attrs={{ "id": id }}. Capitalized Children and Attrs are ordinary inputs.
• Whitespace collapses JSX-style (internal/wsnorm): a newline between elements is dropped (no space); a same-line run of spaces collapses to one. So inline tokens split across elements on separate lines render with no space between them — put an explicit space inside an element (<span> → </span>, <span>label: </span>) or keep them on one line. Bodies of pre/textarea/script/style are kept verbatim.

Forms

• Interpolation: { expr } (auto-escaped per context: HTML/attr/URL/CSS). Opt-outs, each bypassing one check: gsx.Raw(s) (HTML), gsx.RawURL(s) (URL scheme check), gsx.RawCSS(s) (CSS value-filter). JS/event-handler (on*) contexts are a compile error, not auto-escaped.
• Error handling: a (T, error) interpolation/attr value ({ f() }, name={ f() }) auto-unwraps to T; the error propagates out of the enclosing Render. There is no ? try-marker. To handle the error instead, use { if v, err := f(); err != nil { … } }.
• Attributes: static name="lit", dynamic name={ expr }, boolean bare name, type-driven disabled={ cond } (bool → bare/omitted), spread { expr... }, conditional { if … } / { for … } inside the tag.
• Composable class/style: class={ a, "cls": cond, x } (comma list; "cls": cond is conditional sugar).
• Control flow contributing children: { if/for/switch … { <markup> } }.
• Go escape hatch (no output): {{ stmt }}. Fragments: <>…</>.
• Children: declare children gsx.Node or children ...gsx.Node, then place it with {children}. A component without that parameter rejects a non-empty body.
• Attribute fallthrough: declare attrs gsx.Attrs (or another supported attrs-bag shape), then spread { attrs... } where the component chooses. A component without attrs rejects unmatched attributes and attrs-bag contributors.

Coming from JSX (don't get confused)

Same shape, but the holes are Go, not JavaScript:

• Values are Go: { expr }, name={ expr } — not JS, not template strings.
• class (not className), composable: class={ base, "on": active }.
• Control flow is blocks, not operators: { if c { … } }, { for _, x := range xs { … } } — no &&, ternary, or .map().
• Children: {children} in the body; <C>…</C> at the call site — no props.children.
• Event handlers are strings, not funcs: @click=js`open = !open` (Alpine), not onClick={fn}. No output from {{ stmt }}; gsx.Raw(s) is the dangerouslySetInnerHTML opt-out. Body is emission — no return.
• Same as JSX: <>…</> fragments, positional markup-vs-Go, whitespace collapse.

The one subtlety: markup vs Go

Inside { }, gsx decides markup-vs-Go positionally (the Babel rule): { <div/> } is markup, { a < b } is a Go expression. If a comparison or generic looks like a tag, reach for parentheses or a {{ }} block. See the internal/corpus/testdata/cases/parser/ corpus cases.

When in doubt

Read the matching corpus directory under internal/corpus/testdata/cases/: elements elements/, escaping interpolation/ + security/, control flow control_flow/, components/children/slots components/ + slots/, attributes attrs/ + class/ + style/ + jsattr/, corner cases parser/, method components methods/, fallthrough fallthrough/. Full guide: docs/guide/syntax.md.