datastar-patterns

Files (1)

• SKILL.md

SKILL.md (first lines)

# Datastar Patterns

Concrete implementation patterns for Datastar. For architecture decisions, see `datastar-tao`.

## Quick Reference: Attributes

| Attribute | Purpose | Example |
|-----------|---------|---------|
| `data-on:<event>` | Event handler | `data-on:click="@get('/endpoint')"` |
| `data-bind:<signal>` | Two-way input binding | `data-bind:search` |
| `data-signals` | Initialize signals | `data-signals="{count: 0}"` |
| `data-signals__ifmissing` | Initialize only if absent | `data-signals__ifmissing="{count: 0}"` |
| `data-text` | Set element text content | `data-text="$count"` |
| `data-attr:<attr>` | Set HTML attribute reactively | `data-attr:disabled="$_fetching"` |
| `data-effect` | Run expression on signal change | `data-effect="$selections; $_all = $selections.every(Boolean)"` |
| `data-indicator:<signal>` | Set signal true during requests | `data-indicator:_fetching` |
| `data-init` | Run expression on element init | `data-init="@get('/updates')"` |
| `data-on:intersect` | Trigger when element enters viewport | `data-on:intersect="@get('/more')"` |
| `data-on:interval` | Trigger on a timer | `data-on-interval__duration.5s="@get('/poll')"` |

## Quick Reference: Modifiers

| Modifier | Effect | Example |
|----------|--------|---------|
| `__debounce.Nms` | Delay until input pauses | `data-on:input__debounce.200ms` |
| `__throttle.Nms` | Rate-limit execution | `data-on:scroll__throttle.100ms` |
| `__duration.Ns` | Set interval period | `data-on-interval__duration.5s` |
| `__window` | Listen on window, not element | `data-on:keydown__window` |
| `.leading` | Execute immediately on first tick | `data-on-interval__duration.5s.leading` |

## Quick Reference: SSE Response Format

| Event | Data Fields | Purpose |
|-------|-------------|---------|
| `datastar-patch-elements` | `elements`, `selector` (opt), `mode` (opt) | Update DOM fragments |
| `datastar-patch-signals` | `signals` (JSON) | Update client signals |

Merge modes: `outer` (default — replace element by ID), `append`, `prepend`, `remove`.

## Patterns

### Active Search

Debounced input that queries the server as the user types.

```html
<input type="text" placeholder="Search..."
       data-bind:search
       data-on:input__debounce.200ms="@get('/search')" />
<div id="results"><!-- server replaces this --></div>
```

```go
func handleSearch(w http.ResponseWriter, r *http.Request) {
    query := r.URL.Query().Get("search")
    results := db.Search(query)
    sse := datastar.NewSSE(w, r)
    sse.PatchElements(renderTemplate("results", results))
}
```

### Click to Edit

Inline record editing — toggle between view and edit mode.

```html
<!-- View mode -->
<div id="contact">
    <p>Name: John Doe</p>
    <button data-on:click="@get('/contact/edit')"
            data-indicator:_fetching
            data-attr:disabled="$_fetching">Edit</button>
</div>

<!-- Edit mode (returned by server) -->
<div id="contact">
    <input type="text" data-bind:name />
    <button data-on:click="@put('/contact')"
            data-indicator:_fetching
            data-attr:disabled="$_fetching">Save</button>
    <button data-on:click="@get('/contact/cancel')">Cancel</button>
</div>
```

```go
func handleContactEdit(w http.ResponseWriter, r *http.Request) {
    contact := db.GetContact(r)
    sse := datastar.NewSSE(w, r)
    sse.PatchElements(renderTemplate("contact-edit", contact))
}

func handleContactSave(w http.ResponseWriter, r *http.Request) {
    contact := datastar.ReadSignals[Contact](r)
    db.SaveContact(contact)
    sse := datastar.NewSSE(w, r)
    sse.PatchElements(renderTemplate("contact-view", contact))
}
```

> Signal data automatically becomes the request body — no `<form>` element needed.

### Inline Validation

Server-side field validation triggered as the user types.

```html
<input type="email" required
       aria-live="polite"
       data-bind:email
       data-on:keydown__debounce.500ms="@post('/validate')" />
<p id="email-error"></p>
```

```go
func handleValidate(w http.ResponseWriter, r *http.Request) {
    form := datastar.ReadSignals[FormData](r)
    errors := validate(form)
    sse := datastar.NewSSE(w, r)
    sse.PatchElements(renderTemplate("form-errors", errors))

From danmestas/wardrobe, MIT.

More from danmestas/wardrobe