Skip to content
Skills Library
Programming · Building & coding

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.

Repository
wings ↗
Licence
MPL-2.0
Last repository change
04.08.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.08.2026, without references to retired models or APIs.

Licence

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

  1. The module is three files (same basename)
  2. Minimal working component
  3. PranaMod lifecycle
  4. Template binding syntax
  5. Gotcha 1 — snakecase in binding NAMES (the most common mistake)
  6. Gotcha 2 — handlers that need obj
  7. Handling user interaction (native DOM events)
  8. Parent → child data, child → parent events
  9. Async work, timers, and the teardown caveat
  10. Loading data from a backend (fetch)
Original SKILL.md headings · 373 lines, 1,781 words
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…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.