You are reading the docs for v0.9. Read the latest (v0.10)

Actions

An action is a method on your composition. An event in the browser POSTs to it, the method changes state, and via answers with patches for what changed. There is no route to name and no JSON to decode.

On this page

Handling a click
- Counter
Action signatures
What an action body can do
Arguments
- Vote
Forms: on.Submit or PostForm
File uploads
- Inspect a file
Event modifiers
- Live search
Concurrency
Errors and panics

#Handling a click

#Counter

on.Click takes the method value c.Inc. via addresses it by the method's name and the receiver's place in the page, so the POST goes to this child alone and the answer patches this region. The other demos on the page are untouched.

Try this

Click + and read the POST's URL in the Wire pane: /actions/_via/a/{child}/{id}.
Reload the page: the count starts at 0 again, because a State lives on this tab's connection.

Wire

Use the demo to see its requests and patches here.

Source

package demos

import (
	"github.com/go-via/via"
	"github.com/go-via/via/h"
	"github.com/go-via/via/on"
)

// Counter is the smallest live unit: rendering a State is what earns this
// child its own SSE stream, and a click patches only this region.
type Counter struct{ N via.State[int] }

func (c *Counter) Inc(ctx *via.Ctx) { c.N.Set(c.N.Get() + 1) }
func (c *Counter) Dec(ctx *via.Ctx) { c.N.Set(c.N.Get() - 1) }

func (c *Counter) View() h.H {
	return h.Div(h.Class("row"),
		h.Button(on.Click(c.Dec), h.Str("−")),
		h.Output(c.N.Display()),
		h.Button(on.Click(c.Inc), h.Str("+")),
	)
}

Every DOM event binds the same way: on.Change, on.Keydown, on.Submit, and on.Event for an event without its own function. The …CS twins, such as on.ClickCS, run an expression in the browser and post nothing; they are on Signals.

#Action signatures

signatures.go

type Todos struct {
	Items via.List[Todo]
}

// Argless: bind the method value, no & at the call site.
func (t *Todos) Clear(ctx *via.Ctx) { t.Items.Set(nil) }

// With an argument: the second parameter's type is the arg's type.
func (t *Todos) Delete(ctx *via.Ctx, id int) {
	items := t.Items.Get()
	for i, it := range items {
		if it.ID == id {
			t.Items.Remove(i)
			return
		}
	}
}

func (t *Todos) row(it Todo) h.H {
	return h.Li(
		h.Span(h.Str(it.Title)),
		h.Button(on.Click(on.Bind(t.Delete, it.ID)), h.Str("×")),
	)
}

func (t *Todos) View() h.H {
	return h.Div(
		h.Ul(t.Items.Each(t.row)),
		h.Button(on.Click(t.Clear), h.Str("Clear")),
	)
}

Handler	Result
`func (t T) M(ctx via.Ctx)`	Bind with `on.Click(t.M)`.
`func (t T) M(ctx via.Ctx, v V)`	Bind with `on.Click(on.Bind(t.M, v))`; see Arguments below.
A return value, no Ctx, a second argument without on.Bind	Does not compile: the binders accept `func(*via.Ctx)` or an `on.Bound` only.
A func literal in a loop or an Each row	Compiles, then panics at Mount, or at the first render if the empty value has no rows: every copy has the same Go name, so via cannot tell them apart. Use a method and on.Bind.
A method taken through an interface field, or a value receiver whose type sits at two fields or at none	Compiles, then panics at Mount, or at the first render if the empty value does not reach it: via cannot tell which value the method belongs to. Give the method a pointer receiver and hold the concrete type in the field; a value receiver on the page, or on a type only one field holds, works.

An action returns nothing. Report a failure the user can fix by setting state, such as an error Signal; a panic is a 500. Mount checks the lifecycle hooks' signatures, not actions': the two rows above are the only action checks, and a render has to reach the binding to run them.

An action's id is the method's Go name plus the path of the field it was called on, such as Stats.A. A deploy that reorders fields keeps every button's id; one that renames a field answers 410 to a tab still holding the old name.

#What an action body can do

body.go

func (t *Thread) Reply(ctx *via.Ctx) {
	user, ok := ctx.Session().Get[User]()
	if !ok {
		ctx.Redirect("/login")
		return
	}
	id := ctx.Param[int]("id") // mounted at /thread/{id}
	text := strings.TrimSpace(t.Draft.Get())
	if text == "" {
		t.Error.Set("Write something first.")
		return
	}
	if err := t.store.AddReply(ctx.Context(), id, user.Name, text); err != nil {
		t.Error.Set("Could not save the reply.")
		return
	}
	t.Draft.Set("")
	t.Error.Set("")
}

Call	Gives you
`via.Ctx.Request`	The POST's headers, cookies and RemoteAddr. Read-only: the body is already decoded. On a PostForm submit, FormValue and FormFile.
`via.Ctx.Session`	The browser session: `via.Session.Get`, `via.Session.Put`, and `via.Session.Rotate` after a login.
`via.Ctx.Param`	A {name} segment of the mount path, decoded into T; one that does not decode answers 404. The query string is empty on every action.
`via.Ctx.Context`	A context to pass to slow calls. On a live unit it is cancelled when the tab disconnects.
`via.Ctx.Redirect`	Navigate once the handler returns, on this site only. The answer skips OnReload and the render.
`via.Ctx.RedirectExternal`	The same, to another site: an OAuth provider, a payment page.

The rest is your composition: via.Signal.Set, via.State.Set, via.List.Append, or a plain field, and the render that answers the action shows it. There is no response writer; a download is a separate net/http handler that the page links to. via.Ctx.Tick and via.Ctx.Listen register only in OnInit; in an action they log and do nothing. To re-read a store after the action wrote to it, implement OnReload, which is covered on Compositions.

#Arguments

#Vote

on.Bind(v.Cast, r.Option) puts the row's option index in the action URL as JSON, and Cast receives it as an int. Dispatch accepts only an argument that the render before it bound for that handler, and answers 410 to any other before Cast runs, so the handler can index with it. The tallies are shared with everyone reading this, hence the cap.

Go0
Rust0
Zig0
Elixir0

Try this

Vote for Go, then expand the POST in the Wire pane: its URL ends in ?a=0.
Vote in a second tab. This tab shows the new tally on its next vote, not before: nothing pushes it.

Wire

Use the demo to see its requests and patches here.

Source

package demos

import (
	"sync"

	"github.com/go-via/via"
	"github.com/go-via/via/h"
	"github.com/go-via/via/on"
)

// VoteRow is one poll row. Option is the row's identity — it rides with the
// click, so a vote lands on the option clicked and not on a slot.
type VoteRow struct {
	Option int
	Label  string
	Count  int
}

var voteOptions = []string{"Go", "Rust", "Zig", "Elixir"}

// votes is shared by every visitor, which is why Vote is rate limited.
var votes = struct {
	mu     sync.Mutex
	counts []int
}{counts: make([]int, len(voteOptions))}

// The tallies have no topic, so a change is not pushed: an open tab redraws on
// its next vote or reload rather than at the moment of reset.
func resetVotes() {
	votes.mu.Lock()
	clear(votes.counts)
	votes.mu.Unlock()
}

func voteRows() []VoteRow {
	votes.mu.Lock()
	defer votes.mu.Unlock()
	rows := make([]VoteRow, len(voteOptions))
	for i, label := range voteOptions {
		rows[i] = VoteRow{Option: i, Label: label, Count: votes.counts[i]}
	}
	return rows
}

// Vote is a per-row action: each button carries its own option index, and the
// handler receives it as a typed parameter.
type Vote struct {
	// Limiter: see shared_contract.go.
	Lim    Limiter
	Rows   via.List[VoteRow]
	Notice via.State[string]
}

// NewVote takes the limiter the page owns; a nil one is a wiring mistake, so
// it fails here rather than on the first render.
func NewVote(lim Limiter) Vote {
	if lim == nil {
		panic("demos: NewVote: Vote.Lim must not be nil")
	}
	return Vote{Lim: lim}
}

func (v *Vote) OnInit(ctx *via.Ctx) error {
	v.Rows.Set(voteRows())
	return nil
}

func (v *Vote) Cast(ctx *via.Ctx, option int) {
	if !v.Lim.Allow(ctx) {
		v.Notice.Set("Slow down — the tallies are shared, so this demo takes 30 votes a minute.")
		return
	}
	votes.mu.Lock()
	// Indexing on a client value is safe: only an arg this connection's own
	// render bound is dispatchable, so option is one of the rendered rows.
	votes.counts[option]++
	votes.mu.Unlock()

	v.Notice.Set("")
	v.Rows.Set(voteRows())
}

func (v *Vote) row(r VoteRow) h.H {
	return h.Li(h.Class("row"),
		h.Button(on.Click(on.Bind(v.Cast, r.Option)), h.Str("vote")),
		h.Span(h.Str(r.Label)),
		h.Output(h.Str(r.Count)),
	)
}

func (v *Vote) View() h.H {
	return h.Div(
		h.Ul(h.Class("tally"), v.Rows.Each(v.row)),
		h.P(h.Class("notice"), v.Notice.Display()),
	)
}

#Forms: on.Submit or PostForm

#In-place submit

on.Submit on a <form> stops the native submit and posts the tab's signals as JSON, so the text box is a bound Signal and Add reads it with Get. The answer is a patch: the note appears, Set("") empties the box, and focus and scroll stay where they were.

Try this

Submit an empty box: the error arrives as a signal patch.
Add six notes: the list keeps the last five, and the page never reloads.

Wire

Use the demo to see its requests and patches here.

Source

package demos

import (
	"strings"

	"github.com/go-via/via"
	"github.com/go-via/via/h"
	"github.com/go-via/via/on"
)

// Note submits in place: on.Submit posts the tab's signals as JSON, so the
// field is a bound Signal, not a form value, and the answer patches this
// region instead of loading a new page.
type Note struct {
	Draft via.Signal[string]
	Err   via.Signal[string]
	// trim: see shared_contract.go.
	Notes via.List[string]
}

func (n *Note) Add(ctx *via.Ctx) {
	text := strings.TrimSpace(n.Draft.Get())
	if text == "" {
		n.Err.Set("Write something first.")
		return
	}
	if len([]rune(text)) > 80 {
		n.Err.Set("80 characters at most.")
		return
	}
	n.Notes.Append(text)
	trim(&n.Notes, 5)
	n.Draft.Set("")
	n.Err.Set("")
}

func (n *Note) View() h.H {
	return h.Div(
		h.Form(h.Class("row"), on.Submit(n.Add),
			h.Input(n.Draft.Bind(), h.Placeholder("a note"), h.AutoComplete("off")),
			h.Button(h.Type("submit"), h.Str("Add")),
		),
		h.Small(h.Class("err"), n.Err.Display()),
		h.Ul(n.Notes.Each(n.row)),
	)
}

func (n *Note) row(s string) h.H { return h.Li(h.Str(s)) }

#Native submit

via.PostForm renders a native multipart form, so the submit is a real navigation and the handler reads fields with ctx.Request().FormValue. Validation is server-side, and the page comes back with the errors and whatever was typed.

Try this

Submit with one letter in Name: the page reloads with the error and your input kept.
Sign up with valid input: the counter above is back to 0, because the whole document was replaced.

Wire

Use the demo to see its requests and patches here.

Source

package demos

import (
	"strings"

	"github.com/go-via/via"
	"github.com/go-via/via/h"
)

// Signup validates on the server. via.PostForm renders a native multipart
// form, so the submit is an ordinary navigation: the handler reads the fields
// with stdlib and the whole page is rendered again from what it left here.
//
// The errors are plain fields, not State: a navigation opens a new connection,
// which would reseed a State before the reader ever saw it. Anything that must
// outlive the submit goes in the session or a store; here it need only survive
// into the response this very request renders.
type Signup struct {
	name, email              string
	nameErr, mailErr, thanks string
}

func (s *Signup) Submit(ctx *via.Ctx) {
	s.name = strings.TrimSpace(ctx.Request().FormValue("name"))
	s.email = strings.TrimSpace(ctx.Request().FormValue("email"))
	s.nameErr, s.mailErr, s.thanks = "", "", ""

	if len([]rune(s.name)) < 2 {
		s.nameErr = "Two characters at least."
	}
	if !strings.Contains(s.email, "@") {
		s.mailErr = "That is not an address."
	}
	if s.nameErr != "" || s.mailErr != "" {
		return // no Redirect: the page comes back with the errors and the input
	}

	s.thanks = "Welcome, " + s.name + "."
	s.name, s.email = "", ""
}

func (s *Signup) View() h.H {
	return via.PostForm(s.Submit,
		h.Label(h.Str("Name"),
			h.Input(h.Name("name"), h.Value(s.name), h.AutoComplete("off")),
			h.Small(h.Class("err"), h.Str(s.nameErr)),
		),
		h.Label(h.Str("Email"),
			h.Input(h.Name("email"), h.Value(s.email), h.AutoComplete("off")),
			h.Small(h.Class("err"), h.Str(s.mailErr)),
		),
		h.Button(h.Type("submit"), h.Str("Sign up")),
		h.P(h.Class("notice"), h.Str(s.thanks)),
	)
}

	on.Submit	via.PostForm
Request	Datastar fetch, signals as JSON	browser form POST, multipart
Handler reads	bound Signals, with Get	`ctx.Request().FormValue`
Answer	patches for what changed	a whole new document
ctx.Redirect	a navigation script Datastar runs	303 See Other
Files	no	yes
Body cap	`via.WithMaxBody`, 1 MiB	`via.WithMaxUpload`, 8 MiB

Use on.Submit for anything that stays on the page. Use PostForm for sign-in, uploads, and flows that end in a redirect.

#PostForm with bound Signals

profile.go

type Profile struct {
	Name    via.Signal[string]
	Country via.Signal[string] `via:"init=\"pt\""`
	Region  via.Signal[string]
	err     string
}

func (p *Profile) CountryChanged(ctx *via.Ctx) { p.Region.Set("") }

func (p *Profile) Save(ctx *via.Ctx) {
	r := ctx.Request()
	p.Name.Set(strings.TrimSpace(r.FormValue("name")))
	p.Country.Set(r.FormValue("country"))
	p.Region.Set(r.FormValue("region"))
	if p.Name.Get() == "" {
		p.err = "Name is required."
	}
}

func (p *Profile) View() h.H {
	return via.PostForm(p.Save,
		h.Input(h.Name("name"), p.Name.Bind()),
		h.Select(h.Name("country"), p.Country.Bind(), on.Change(p.CountryChanged),
			h.Option(h.Value("pt"), h.Str("Portugal")),
			h.Option(h.Value("br"), h.Str("Brasil"))),
		h.Select(h.Name("region"), p.Region.Bind(), via.Each(regions[p.Country.Get()], option)),
		h.Small(h.Str(p.err)),
		h.Button(h.Type("submit"), h.Str("Save")),
	)
}

A form can keep Signals on its inputs, so an on.Change reshapes it before the submit: here the country picks the region list. The submit is native: it posts fields by name, not the signal store, so in the handler via.Signal.Get returns the initial value. Give each bound input an h.Name, read it with FormValue, and via.Signal.Set the Signal from it. The answer renders those values, with the error beside them.

#File uploads

#Inspect a file

PostForm always sends multipart/form-data, so ctx.Request().FormFile works in the handler. This one hashes the bytes, sniffs the type from the first 512, and keeps nothing.

Try this

Upload a PNG renamed to .txt: the sniffed type ignores the name and the claimed type.
Submit with no file chosen.

Wire

Use the demo to see its requests and patches here.

Source

package demos

import (
	"crypto/sha256"
	"encoding/hex"
	"io"
	"net/http"
	"strconv"

	"github.com/go-via/via"
	"github.com/go-via/via/h"
)

// Upload reads a file from a native multipart submit and keeps nothing: it
// hashes the bytes, sniffs the type and reports both. The results are plain
// fields for the same reason as Signup's: the submit is a navigation, and they
// only have to reach the page this request renders.
type Upload struct {
	// Limiter: see shared_contract.go.
	Lim    Limiter
	report []string
	err    string
}

func NewUpload(lim Limiter) Upload {
	if lim == nil {
		panic("demos: NewUpload: Upload.Lim must not be nil")
	}
	return Upload{Lim: lim}
}

func (u *Upload) Inspect(ctx *via.Ctx) {
	if !u.Lim.Allow(ctx) {
		u.err = "Slow down: this demo takes 10 uploads a minute."
		return
	}
	f, hdr, err := ctx.Request().FormFile("file")
	if err != nil {
		u.err = "Pick a file first."
		return
	}
	defer f.Close()

	head := make([]byte, 512)
	n, _ := io.ReadFull(f, head)
	sum := sha256.New()
	sum.Write(head[:n])
	size, err := io.Copy(sum, f)
	if err != nil {
		u.err = "The upload broke off."
		return
	}
	u.report = []string{
		"name (client-supplied): " + hdr.Filename,
		"size: " + strconv.FormatInt(size+int64(n), 10) + " bytes",
		"sniffed type: " + http.DetectContentType(head[:n]),
		"claimed type: " + hdr.Header.Get("Content-Type"),
		"sha256: " + hex.EncodeToString(sum.Sum(nil))[:16] + "…",
	}
}

func (u *Upload) View() h.H {
	rows := make([]h.H, 0, len(u.report))
	for _, r := range u.report {
		rows = append(rows, h.Li(h.Str(r)))
	}
	return via.PostForm(u.Inspect,
		h.Div(h.Class("row"),
			h.Input(h.Type("file"), h.Name("file")),
			h.Button(h.Type("submit"), h.Str("Inspect")),
		),
		h.Small(h.Class("err"), h.Str(u.err)),
		h.Ul(rows...),
	)
}

A handler that keeps the file names it and checks it itself:

upload.go

func (a *Avatar) Save(ctx *via.Ctx) {
	f, _, err := ctx.Request().FormFile("avatar")
	if err != nil {
		a.msg = "Pick a file."
		return
	}
	defer f.Close()

	head := make([]byte, 512)
	n, _ := io.ReadFull(f, head)
	if http.DetectContentType(head[:n]) != "image/png" {
		a.msg = "PNG only."
		return
	}
	// The name is yours, never the client's header.Filename.
	dst, err := os.CreateTemp("/var/uploads", "avatar-*.png")
	if err != nil {
		a.msg = "Could not save."
		return
	}
	defer dst.Close()
	if _, err := f.Seek(0, io.SeekStart); err != nil {
		a.msg = "Could not save."
		return
	}
	if _, err := io.Copy(dst, f); err != nil {
		a.msg = "Could not save."
		return
	}
	ctx.Redirect("/profile")
}

func (a *Avatar) View() h.H {
	return via.PostForm(a.Save,
		h.Input(h.Type("file"), h.Name("avatar"), h.Accept("image/png")),
		h.Button(h.Type("submit"), h.Str("Upload")),
		h.P(h.Str(a.msg)),
	)
}

upload.go

func newRouter() *via.Router {
	return via.NewRouter(
		via.WithMaxUpload(20<<20), // whole body; over it is 413
		via.WithMaxBody(1<<20),    // held in RAM; the rest spills to disk
	)
}

via.WithMaxUpload caps the whole multipart body (default 8 MiB), and a larger one answers 413 before the handler runs. via.WithMaxBody caps how much of it is held in memory (default 1 MiB); via spills the rest to temp files and removes them after the handler returns.

#Event modifiers

#Live search

on.Input fires on every keystroke. on.WithDebounce(300*time.Millisecond) holds the POST until typing stops for 300 ms. The box is a bound Signal, so the handler reads the latest text whatever the timing.

Type part of a standard library package name.

Try this

Type sync quickly and count the POSTs in the Wire pane: one, not four.
Type, pause, type again: one POST per pause.

Wire

Use the demo to see its requests and patches here.

Source

package demos

import (
	"strings"
	"time"

	"github.com/go-via/via"
	"github.com/go-via/via/h"
	"github.com/go-via/via/on"
)

var stdlib = []string{
	"bufio", "bytes", "cmp", "context", "crypto/rand", "crypto/sha256", "database/sql",
	"embed", "encoding/base64", "encoding/csv", "encoding/json", "errors", "flag", "fmt",
	"hash/maphash", "html/template", "io", "io/fs", "iter", "log", "log/slog", "maps",
	"math", "math/big", "math/rand/v2", "mime/multipart", "net", "net/http",
	"net/http/httptest", "net/netip", "net/url", "os", "os/exec", "os/signal",
	"path/filepath", "reflect", "regexp", "runtime", "slices", "sort", "strconv",
	"strings", "sync", "sync/atomic", "testing", "text/template", "time", "unicode/utf8",
	"unique", "unsafe",
}

// Search filters on the server as you type. The input is a bound Signal, so
// every keystroke updates the signal in the browser; on.WithDebounce holds the
// POST until typing pauses, and the handler sees the latest value.
type Search struct {
	Query via.Signal[string]
	hits  []string
	asked bool
}

func (s *Search) Run(ctx *via.Ctx) {
	q := strings.ToLower(strings.TrimSpace(s.Query.Get()))
	s.asked, s.hits = q != "", nil
	for _, p := range stdlib {
		if q != "" && strings.Contains(p, q) {
			s.hits = append(s.hits, p)
		}
	}
}

func (s *Search) View() h.H {
	status := "Type part of a standard library package name."
	if s.asked && len(s.hits) == 0 {
		status = "No match."
	}
	rows := make([]h.H, 0, len(s.hits))
	for _, p := range s.hits {
		rows = append(rows, h.Li(h.Code(h.Str(p))))
	}
	return h.Div(
		h.Input(s.Query.Bind(), on.Input(s.Run, on.WithDebounce(300*time.Millisecond)),
			h.Type("search"), h.Placeholder("http, sync, …"), h.AutoComplete("off")),
		h.P(h.Class("notice"), h.Str(status)),
		h.Ul(rows...),
	)
}

Option	Effect	Datastar modifier
`on.WithDebounce`	Runs once the event has stopped firing for d.	`__debounce.300ms`
`on.WithThrottle`	Runs at most once per d.	`__throttle.300ms`
`on.WithOnce`	Removes the listener after its first run.	`__once`
`on.WithPrevent`	Calls preventDefault. Not needed with on.Submit.	`__prevent`
`on.WithStop`	Calls stopPropagation.	`__stop`
`on.WithOutside`	Fires only for events whose target is outside the element.	`__outside`
`on.WithWindow`	Listens on window instead of the element.	`__window`
`on.WithModifier`	Any other Datastar modifier, such as delay.300ms or passive. A modifier a typed option covers panics.	`__delay.300ms`

The options take the same form on the …CS twins. A duration of zero or less panics, and so do two different durations for one option on the same binding.

#Concurrency

On a plain unit every action POST gets its own copy of the composition and runs on its own net/http goroutine. Two POSTs from one tab never share memory, but they can run at the same time and finish in either order.

On a live unit, one that renders a State or List or registers a Tick or Listen, every action, Tick and Listen handler for the tab runs on that tab's stream goroutine, one at a time, and the POST waits for its turn.

Neither protects what you share outside the composition. A package-level map, a store, or a tally every visitor sees needs its own lock, as Vote's does. In the browser, Datastar aborts an in-flight request when the same binding fires again, so a double click reads only the second answer; the first may still have run on the server.

#Errors and panics

Status	When
400	The ?a= argument does not decode into the handler's type, or the body is malformed. A JSON body without Datastar-Request: true is read as a form, and the 400 names the header.
403	The Origin is not trusted (see `via.WithTrustedOrigin`), the tab's stream is bound to another session, or OnInit or OnReload returned `via.ErrForbidden`.
404	A path segment does not decode for ctx.Param, or OnReload returned `via.ErrNotFound`.
410	The render does not bind this action, or not with this argument, or the tab's stream is gone.
413	The body is over WithMaxBody, or a native submit is over WithMaxUpload.
500	The handler panicked, or OnReload returned any other error. The panic is logged with its stack, and the process keeps serving.
503	The session store did not answer, a live tab's goroutine did not pick the action up in time, too many actions are already waiting for their streams, or the router is shutting down.

An action posted by Datastar leaves the page as it was. On a page with a live unit, a 410 shows "Page is out of date" and reloads. Any other failure (a 500 from a handler panic, a 503, a 403) shows nothing. Listen for the datastar-fetch event of type error to show your own notice. A PostForm submit navigates to the error response: plain text, or the document via.WithErrorPage renders.