wings-component
/wings-component
Write a WINGS component (custom element in Go→WASM) — module file trio, wings.Register, the PranaMod lifecycle (InitData/Render), template binding syntax ({{expr}}, ?cond, *arr/**arr, &attr, @event), and parent-child events. Use when creating or editing a WINGS module, template, custom element, PranaMod, or any template binding.
- Author
- luisfurquim ↗
- Repository
- wings ↗
- Licence
- MPL-2.0
- Last repository change
- 04.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 04.08.2026, without references to retired models or APIs.
MPL-2.0, otwarta.
What it does and when to use it
Write a WINGS component (custom element in Go→WASM) — module file trio, wings.Register, the PranaMod lifecycle (InitData/Render), template binding syntax ({{expr}}, ?cond, *arr/**arr, &attr, @event), and parent-child events. Use when creating or editing a WINGS module, template, custom element, PranaMod, or any template binding.
Original author description
Write a WINGS component (custom element in Go→WASM) — module file trio, wings.Register, the PranaMod lifecycle (InitData/Render), template binding syntax ({{expr}}, ?cond, *arr/**arr, &attr, @event), and parent-child events. Use when creating or editing a WINGS module, template, custom element, PranaMod, or any template binding.
How it works
- The module is three files (same basename)
- Minimal working component
- PranaMod lifecycle
- Template binding syntax
- Gotcha 1 — snakecase in binding NAMES (the most common mistake)
- Gotcha 2 — handlers that need obj
- Handling user interaction (native DOM events)
- Parent → child data, child → parent events
- Async work, timers, and the teardown caveat
- Loading data from a backend (fetch)
SKILL.md preview
---
name: wings-component
description: Write a WINGS component (custom element in Go→WASM) — module file trio, wings.Register, the PranaMod lifecycle (InitData/Render), template binding syntax ({{expr}}, ?cond, *arr/**arr, &attr, @event), and parent-child events. Use when creating or editing a WINGS module, template, custom element, PranaMod, or any template binding.
---
# Writing a WINGS component
A component is a custom element whose logic is **Go compiled to WASM**. Read
`AGENTS.md` at the repo root first for the mental model and the two
non-negotiable gotchas; this skill is the working detail.
## The module is three files (same basename)
```
mymod/
mymod.go # init() registers + the PranaMod implementation
mymod.html # template with bindings
mymod.css # styles (shadow-DOM scoped)
```
Every component `.go` file starts with `//go:build js && wasm`.
## Minimal working component
`mymod.go`:
```go
//go:build js && wasm
package mymod
import (
_ "embed"
"github.com/luisfurquim/wings"
)
//go:embed mymod.html
var htmlContent string
//go:embed mymod.css
var cssContent string
type MyMod struct{}
func init() {
wings.Register(
"my-mod", // custom element tag (must contain a hyphen)
htmlContent,
cssContent,
func() wings.PranaMod { return &MyMod{} },
"title", // ...observed attributes (re-render when they change)
)
}
// InitData: initial state. obj is NOT available here.
func (m *MyMod) InitData() map[string]any {
return map[string]any{
"title": "Hello",
"count": 0,
"items": []any{},
"show_extra": false, // snake_case — see gotcha #1
}
}
// Render: runs after connect; obj is available.
func (m *MyMod) Render(obj *wings.PranaObj) {
obj.This.Set("items", []any{
map[string]any{"label": "Alpha"},
map[string]any{"label": "Beta"},
})
}
```
`mymod.html`:
```html
<div class="widget">
<h2>{{title}}</h2>
<p>Count: <span>{{count}}</span></p>
<ul>
<li *items:i>{{items[i].label}}</li>
</ul>
<div ?show_extra>
<p>Extra content</p>
</div>
<input &value="{{input_val}}" type="text" />
</div>
```
App entry point (`main.go`, native to the app, one per app):
```go
//go:build js && wasm
package main
import (
"github.com/luisfurquim/wings"
_ "myapp/mod/mymod" // blank-import every module to register it
)
func main() { wings.Main() }
```
## PranaMod lifecycle
- `InitData() map[string]any` — initial data map. `obj` is **not** ready.
- `Render(obj *wings.PranaObj)` — after the element connects. Here:
- `obj.This` — reactive store: `Set(key, v)`, `Get(key) any`, `Append(key, v)`,
`DeleteAt(key, i)`, `Delete(key)`. Changing data re-renders the DOM.
- `obj.Element` / `obj.Dom` — the element / its shadow root (`js.Value`).
- `obj.Trigger(name, args...)` — fire an event up to the parent.
## Template binding syntax
| Syntax | Meaning |
|---|---|
| `{{x}}`, `{{a.b}}`, `{{arr[i].f}}` | display a value; auto-updates |
| `{{#}}` | current URL hash fragment |
| `?cond` / `?!cond` | show if truthy / falsy |
| `?x="v"` `?x!="v"` `?x^="v"` `?x$="v"` `?x*="v"` | eq / ne / prefix / suffix / contains |
| `*arr:i` | repeat element per item (`i` is the loop index, used as `{{arr[i].field}}`; wrapped in `<span>`) |
| `**arr:i` | repeat first child per item (container kept) |
| `&value="{{v}}"` | two-way bind input/select/textarea |
| `@event="handler"` | route child event to a parent handler |
(i18n flexion/format sigils — `{{@g %n ~word}}`, `{{%price}}` — are covered by
the `wings-i18n` skill.)
### Switching views by state
`?key="value"` shows an element only when the reactive key **equals** that
string, so one status key can drive a set of mutually exclusive views — the
idiom for loading/ready/error and any small state machine. Set the key with
`obj.This.Set`; gate each view with its own equality test:
```go
func (m *MyMod) InitData() map[string]any {
return map[string]any{"status": "loading"}
}
func (m *MyMod) Render(obj *wings.PranaObj) {
go func() {
if err := load(obj); err != nil {
obj.This.Set("status", "error") // flips which view shows
return
}
obj.This.Set("status", "ready")
}()
}
```
```html
<p ?status="loading">Loading…</p>
<p ?status="error">Something went wrong.</p>
<ul ?status="ready"><li *items:i>{{items[i].name}}</li></ul>
```
The compared value is a **data key**, not an attribute literal; changing it via
`obj.This.Set` re-renders and switches the visible view.
## Gotcha #1 — snake_case in binding NAMES (the most common mistake)
The browser lowercases attribute names. A binding **name** with an uppercase
letter (`?isLoading`, `*myItems`, `&myValue`, `showExtra="{{...}}"`) silently
becomes a **no-op**: wrong render, no error. Use snake_case.
- Affected: `?cond`, `*arr`, `**arr`, `&attr`, and any binding written as an
attribute name (e.g. `show_extra="{{show_extra}}"`).
- Exempt: `{{textBinding}}` inside text content (parsed from text, not
attributes) — but use snake_case there too for consistency.
`go run ./cmd/build <target>` scans templates and **fails the build** on any
uppercase binding name with `file:line`. If you hit that, rename to snake_case.
## Gotcha #2 — handlers that need `obj`
`obj` is unavailable in `InitData`. For event handlers (and anything needing
`obj`), put a placeholder in `InitData` and set the real handler in `Render`:
```go
func (a *App) InitData() map[string]any {
return map[string]any{"on_save": wings.TriggerHandler(nil)}
}
func (a *App) Render(obj *wings.PranaObj) {
obj.This.Set("on_save", func(args ...any) {
obj.This.Set("saved", true)
})
}
```
## Handling user interaction (native DOM events)
`@event` (below) is **only** for component events a child raises with
`obj.Trigger`. It does **not** bind a native DOM event such as a button click.
For those, attach a listener in `Render` with the `wings/dom` package: give the
element an `id` in the template, query it from the shadow root (`obj.Dom`), and
add the listener.
```go
import (
"syscall/js"
"github.com/luisfurquim/wings"
"github.com/luisfurquim/wings/dom"
)
func (m *MyMod) Render(obj *wings.PranaObj) {
if els := dom.Query(obj.Dom, "#clear-btn"); len(els) > 0 {
dom.AddEvent(els[0], "click",
func(this js.Value, args []js.Value) any {
obj.This.Set("items", []any{})
obj.Trigger("cleared") // optionally also notify the parent
return nil
}, false, false) // preventDefault, stopPropagation
}
}
```
In the template the element only needs the id: `<button id="clear-btn">Clear</button>`.
There is no `@click` attribute — wiring native events is Go code in `Render`.
To **read a value** off the event target (an `<input>`'s text, a `<select>`'s
value), pull it from `this` inside the handler and **type-check before use**:
every `js.Value` from the DOM is untrusted, and a wrong-type read panics — which
in WASM kills the whole app. This is where the event wiring meets the
`sec-wasm-go` / `sec-hostile-input` rules:
```go
func (m *MyMod) Render(obj *wings.PranaObj) {
if els := dom.Query(obj.Dom, "#search"); len(els) > 0 {
dom.AddEvent(els[0], "input",
func(this js.Value, args []js.Value) any {
v := this.Get("value")
if v.Type() != js.TypeString { // guard: wrong type would panic
return nil
}
obj.This.Set("query", v.String()) // store it; recompute any derived list — see "Derived lists"
return nil
}, false, false)
}
}
```
WINGS frees this listener for you when the component disconnects — no manual
cleanup needed.
## Parent → child data, child → parent events
`@event` routes **component** events (a child raised via `obj.Trigger`), not
native DOM events (see the section above for those).
- **Down:** the parent passes data via attributes:
`<my-child label="{{title}}" ?is_open></my-child>` (child lists `label`,
`is_open` in its observed attributes if they change at runtime).
- **Up:** parent template binds `@event="handler"`; child fires
`obj.Trigger("event", args...)`. The handler is a `func(args ...any)` in the
parent's data (see gotcha #2). `@event` attrs are read at trigger time and do
**not** need to be observed.
## Async work, timers, and the teardown caveat
Do background or periodic work in `Render`: launch a goroutine and write results
through `obj.This.Set` (safe — WASM is single-threaded and the model re-renders).
Drive timing with `setTimeout` via the core helpers (or Go's `time`).
```go
func (m *MyMod) Render(obj *wings.PranaObj) {
go func() {
for obj.Element.Get("isConnected").Bool() { // stop when removed — see caveat
done := make(chan struct{})
wings.JSGlobal().Call("setTimeout", wings.JSFuncOnce(func() {
n, _ := obj.This.Get("count").(int)
obj.This.Set("count", n+1)
close(done)
}), 1000)
<-done
}
}()
}
```
**Teardown caveat:** `PranaMod` has only `InitData` and `Render` — there is **no
disconnect/teardown hook**, and `Render` gets no cancellation context. On
disconnect WINGS frees what it can see (two-way bindings, the render goroutine,
`dom.AddEvent` listeners and `dom.Observe` MutationObservers under the
element), but it **cannot interrupt a
goroutine you launched**: a loop that never exits keeps running after the
element leaves the DOM. For app-lifetime components that is harmless; for
components created and destroyed repeatedly, guard the loop with
`obj.Element.Get("isConnected").Bool()` and return when false. Never write a
`for {}` or `for range ticker.C` with no exit condition.
## Loading data from a backend (`fetch`)
You don't need a WINGS API for HTTP — Go's standard `net/http` **works as-is**
under `GOOS=js`: the runtime maps it onto the browser's Fetch API. The
non-obvious parts (this is the kind of thing that's easy to get subtly wrong):
- **Always from a goroutine** launched in `Render`, never inline — a blocking
request on the event-loop path freezes the page (WASM is single-threaded).
- **Relative URLs are same-origin** (`/api/...` resolves against the page); a
cross-origin call needs the server's CORS headers.
- **Cookies/credentials aren't sent cross-origin by default.** To include them,
build the request and set a Fetch-option header —
`req.Header.Set("js.fetch:credentials", "include")` — using
`http.NewRequest` + `client.Do` (plain `http.Get` gives you no place to set
it). Other `js.fetch:` headers (`mode`, `redirect`) tune the fetch the same way.
- **Raw sockets don't exist** in the browser — only `net/http` (fetch).
`net.Dial`/TCP/UDP are unavailable; don't reach for them.
- **Validate what comes back** at this boundary: check the status, then decode
into a *concrete struct* (not `map[string]any`) — see `sec-hostile-input`. The
body is untrusted; never put it into `innerHTML` (`sec-wasm-go`). Drive the
DOM through `obj.This`, as always.
```go
func load(obj *wings.PranaObj) error {
cli := &http.Client{Timeout: 15 * time.Second} // Timeout maps to AbortController
resp, err := cli.Get("/api/items")
if err != nil {
return err
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusOK {
return fmt.Errorf("backend: %s", resp.Status)
}
var items []Item // concrete shape, parsed exactly once here
dec := json.NewDecoder(resp.Body)
dec.DisallowUnknownFields()
if err := dec.Decode(&items); err != nil {
return err
}
obj.This.Set("items", toAny(items)) // reactive store → DOM updates
return nil
}
```
## Derived lists (search / filter / sort)
The reactive store holds **plain values** — `Set`/`Get`/`Append`/`DeleteAt`/
`Delete`. There are **no computed/derived values**: setting one key never
recomputes another. So to show a filtered or sorted view of a list, keep two
keys — the immutable source and the derived view — and recompute the derived
one yourself whenever an input changes, writing it back with `Set`:
```go
func (m *MyMod) InitData() map[string]any {
return map[string]any{"all": []any{}, "visible": []any{}, "query": ""}
}
// recompute "visible" from the source "all" + current "query"
func applyFilter(obj *wings.PranaObj) {
all, _ := obj.This.Get("all").([]any)
q, _ := obj.This.Get("query").(string)
q = strings.ToLower(strings.TrimSpace(q))
out := make([]any, 0, len(all))
for _, item := range all {
row, _ := item.(map[string]any)
name, _ := row["author"].(string)
if q == "" || strings.Contains(strings.ToLower(name), q) {
out = append(out, row)
}
}
obj.This.Set("visible", out)
}
```
Call `applyFilter(obj)` from the search handler (right after
`Set("query", …)`) and after you populate `all`. The template repeats the
**derived** key — `<li *visible:i>{{visible[i].author}}</li>` — so the source
list stays intact while the view updates.
## Before you finish
- Run `go run ./cmd/build <target>` — it lints (catches gotcha #1) and builds.
- Single root element in the template avoids an auto `<span>` wrapper.
- Never set innerHTML or touch the DOM directly for data display — drive it
through `obj.This`.
Deeper reference: README "Template Syntax", "Reactive Data API", "Parent-Child
Communication", "Full Example". Sibling skills: `wings-i18n`, `wings-skins`,
`wings-widgets` (tabs/dialog/combobox — don't hand-roll them), `wings-build`.
Versions
The database has no other skills named wings-component.
Database snapshot: 13.11.2026 · package version 9d2df384cb58 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100wings-build
Set up, build, and serve a WINGS app — Go module setup, the WASM build (GOOS=js), copying the JS runtime helpers, a static dev server, and the cross-platform cmd/build orchestrator (targets + the camelCase binding lint + rebuild-on-save dev mode). Use when scaffolding a new… - 100wings-skins
Theme a WINGS app with --wings-* skin tokens — consume tokens in component CSS via var() with fallbacks, apply/compose built-in skins (ApplySkin), the ten disjoint skin categories and multi-skin composition, register your own skin, bundles (composed skins), and private… - 100design-api
Design a custom element's public API e.g. attributes, properties, events, slots, CSS parts and custom properties. Use when the user asks to "design an element", "plan a component API", "create element API", "design component interface", or discusses naming conventions, API… - 95wasm
WebAssembly (WASM) integration, WASI, component model, Rust/Go to WASM compilation. Use when implementing WASM modules, browser/edge compute, or polyglot runtime. - 90frontend-web-components
Use this skill when the user says 'web component', 'custom element', 'shadow DOM', 'HTML template', 'CustomElementsRegistry', 'ElementInternals', 'form-associated element', 'cross-framework component', 'vanilla web component'. This skill enforces: custom element lifecycle…