# Forms & validation Rask binds inputs two-way with a strongly-typed `Bind` expression, validates each field by the rule written beside it — `.Validate(…)` — and tracks per-field state (touched / modified / messages / in-flight validation) on an `EditContext`. The same component code runs server-rendered or on WASM. This guide builds up in layers: binding → forms → inline validation, sync and async → nested models → radio/checkbox groups. DataAnnotations and FluentValidation are supported too, for a model that already carries them. For the analyzer IDs referenced here (`RASK001`, `RASK022`, …) see [diagnostics.md](https://rask.sh/docs/guides/diagnostics/). ## On this page - [Validation](https://rask.sh/docs/guides/forms-validation/) — inline `.Validate(…)` on a field or the form, async rules, rules in a value object; then DataAnnotations and FluentValidation. - [Nested models & control groups](https://rask.sh/docs/guides/forms-advanced/) — complex models, radio/checkbox groups, custom controls. --- ## 1. Two-way binding The low-level path wires `Value` and an event handler yourself: ```csharp Input.Value(_typed).Type(InputType.Text).OnInput(v => _typed = v) P[$"Echo: {_typed}"] ``` The ergonomic path is a `Bind` expression — one call replaces `Value` + `OnInput` + parsing: ```csharp Input.Bind(() => _model.Name).Live().Placeholder("Your name") P[$"Hello, {_model.Name}!"] ``` `.Live()` is there because the page reads the name back while it is typed. A bound field that is only read when the form is saved does not need it — see [bind timing](#bind-timing). `Bind` is an `Expression>`. The chain step reads the expression and derives everything from the bound property: - **Input name** ← the property name (`name="Name"`). Override with `Name:`. - **Input type** ← the property's CLR type (`BindingHelpers.DefaultInputType`): `bool → checkbox`, every numeric primitive `→ number`, `DateOnly → date`, `DateTime`/`DateTimeOffset` `→ datetime-local`, `TimeOnly`/`TimeSpan` `→ time`, everything else `→ text`. Override with `Type:` — an `InputType` enum value. The full set is `Text`, `Search`, `Tel`, `Url`, `Email`, `Password`, `Number`, `Checkbox`, `Radio`, `File`, `Range`, `Color`, `Date`, `DatetimeLocal` (renders `datetime-local`), `Time`, `Week`, `Month`, `Hidden`, `Button`, `Submit`, `Reset`, `Image`. The *string-only* family (`Text`/`Search`/`Tel`/`Url`/`Email`/ `Password`) only makes sense on an `HTMLInputElement`; setting one on a non-string bound input is [RASK025](https://rask.sh/docs/guides/diagnostics/#rask025). - **Passwords are the browser's.** An input of `type=password` (or `autocomplete` `current-password`, `new-password` or `one-time-code`) sends what was typed to the model and never gets it back: the server writes `""` to clear it and nothing else, so a model value set from the server does not reach the field, and a page that prefills a password is a bug in the page. - **Update timing** — a bound control says nothing until the next action, and its value travels with that: see [bind timing](#bind-timing). ### Bind timing **A bound control waits for the next action.** Typing into it, choosing in it and leaving it send nothing, run no rule and render nothing. When the reader presses a button, submits, or does anything else the page hears, everything they entered is sent first, in order, and then the action. This is how Livewire's `wire:model` works, and Flux's forms with it. Three steps after `Bind` say otherwise: ```csharp Input.Bind(() => _m.Name) // waits: the value travels with the next action Input.Bind(() => _m.Title).Live() // as it is typed, after a 150 ms pause Input.Bind(() => _m.Code).Live().Debounce(300.Milliseconds) // a pause of your own Input.Bind(() => _m.Notes).Blur() // on leaving the field Select.Bind(() => _m.Country).Live() // as soon as it is picked ``` | Step | Livewire | Writes the model and runs the rules | | --- | --- | --- | | *(none)* | `wire:model` | with the next action | | `.Live()` | `wire:model.live` | as the reader types, 150 ms after the last key; at once for a checkbox, a radio, a select, a range | | `.Debounce(300.Milliseconds)` | `wire:model.live.debounce.300ms` | as the reader types, after that pause. Implies `.Live()`; `TimeSpan.Zero` sends every keystroke | | `.Blur()` | `wire:model.live.blur` (`.blur` before v4) | on leaving the field | **Say `.Live()` on a control you read while the reader is still in the form**: a greeting that echoes a name, a character count, a total, a select that fills a second select, a checkbox that shows a section, a filter. A control you only read in the submit handler needs nothing. - **An action** is anything that reaches your code: a press on a button or a link with a handler, a submit, Enter in a field, a key an `OnKeyDown` hears, another control's `.Live()` or `.Blur()` change, a navigation, an event a kit component raises into your code (a tab with `OnChange`, a menu item, a dragged row). Each is preceded by the values that waited, so a handler never reads a model that has not heard what was typed. - **A kit control drawing itself is not an action.** Opening a `Ui.Select`, a `Ui.Dropdown`, a date or a time picker, moving its cursor with the arrows or the pointer, typing in its search field, paging a calendar: the page hears those only because it is what draws the control, and in Flux they are no request at all. Nothing that waits is written for them, so a rule of a field above the list does not speak when the list is opened. A **pick** in a bound control that waits is the same — the pick itself waits. What does count: a pick in a control that says `.Live()` or is held with `Value`/`OnChange`, a search field with an `OnInput` of yours, a `Ui.Dropdown.OnToggle`, a `Ui.Tabs.OnChange`, a "create" row — anything that reaches your code. - **What the page does by itself is not an action.** A toast whose time is up closing itself, a chart reporting the size it was measured at, a list scrolling, a video playing on, an animation ending, an image arriving, the reply to a JavaScript call, a call your script makes into .NET: none of them writes a field the reader is still typing in, and none runs its rules. Their handlers run; what waits goes on waiting for the reader. - **A render the server starts** — a timer, a push, a handler that finishes later — cannot ask the browser first. It sees the model as of the last action, and it does not take back what the reader has entered since: the text stays in the field, the box stays ticked, and both still travel with the next action. - **Validation follows the value.** A field that waits shows no message while it is typed into or left; its rules run when its value arrives, and all of them on submit. `.Live()`, `.Debounce(…)` and `.Blur()` fields validate when they write. - **A message goes as soon as the reader starts correcting it** — at the first key, and no rule runs for that. This is the one thing a waiting field sends while it is typed into: a message with no value in it, once, and only while a message shows. - **The unsaved-changes guard** ([`ConfirmLeave`](#ask-before-leaving-unsaved-changes)) counts the first keystroke, sent or not. - **A rule still running when Save is pressed is not saved past**: the submit runs every rule again and waits for the answers. - **`AfterBind`** runs when the value is written — with the action for a control that waits. `.Live()` is on every bound control of Core: `Input`, `Textarea`, `Select`. `.Debounce(…)` and `.Blur()` are on `Input`, `Textarea`, `Ui.Input` and `Ui.Textarea`, for a field that is typed into — text, number, date. A checkbox, a radio, a range and a colour are chosen rather than typed: with either step they simply write as they are chosen. A file input's files travel with the submit, as in any form; `OnFiles` is an event of its own and is not bound. One thing defeats a pause, by sending the value early: an `OnKeyDown` or `OnKeyUp` on the field that hears every key. Give it [`data-rask-keys`](https://rask.sh/docs/guides/js-interop-runtime/#keys-and-focus) and it hears only the keys it acts on. The kit's `Ui.Input` and `Ui.Textarea` forward all three steps to Core's. **Every chosen control of the kit follows the same rule**, and `.Live()` is on each of them: `Ui.Checkbox`, `Ui.Switch`, `Ui.Select` (native, listbox, combobox, multiple), `Ui.Pillbox`, `Ui.Autocomplete`, `Ui.CheckboxGroup`, `Ui.RadioGroup`, `Ui.Slider`, `Ui.Otp`, `Ui.Calendar`, `Ui.DatePicker`, `Ui.TimePicker`, `Ui.Editor`, `Ui.Tabs`, `Ui.MenuCheckbox` and `Ui.MenuRadioGroup`. ```csharp Ui.Select.Bind(() => m.Plan).Listbox[…] // the list shows the pick; the model hears it with the next action Ui.Select.Bind(() => m.Country).Live()[…] // written on pick: AfterBind and a dependent select react at once Ui.Checkbox.Bind(() => m.Agreed).Live() // a section that shows while it is ticked Ui.DatePicker.Bind(() => m.From).Live() // a price that follows the date ``` - **A control of one element** — `Ui.Checkbox`, `Ui.Switch`, the native `Ui.Select` — waits in the browser, as an input does: ticking it sends nothing at all. - **A control the kit draws in C#** — a listbox, a calendar, a group, a slider — still sends its own event, because the server draws the pick: the list shows the option, the calendar the day. What waits is the **write**: the model, the member's rules and `AfterBind` hear the value with the next action, in the order the controls were last touched, before the action's own handler. Nothing the page wrote runs per pick, and the page is not rendered again for one — only the control. - **What counts as the next action here** is any handler that is not such a control drawing itself: a button of the page, a submit, another control's `.Live()` change, a controlled control's `OnChange`, and a callback the control itself raises into the page — `Ui.Otp`'s `OnComplete`, a tab's `OnClick`, a select's `OnInput` — which finds the model written. - **Two controls that wait do not write each other.** A pick in the calendar leaves the listbox's pick waiting: a waiting control drawing itself is never an action, whichever control it is. - **A listbox's pick is checked when it is written.** A bound `Ui.Select.Listbox` used to run its member's rules on submit only; they now run when the value arrives, like any bound control's. - **Not preceded: a callback that captures no component.** The waiting picks are written ahead of a callback by way of the component that wrote it. A `static` lambda, or one that closes over locals only (`.OnComplete(_ => row.Done = true)` in a loop over rows), belongs to no component and runs without them; write it so that it touches the component (`_ => Finish(row)`). - **A message under a control that waits** goes when the reader picks again, as it goes under a field at the first key. The pick marks the field modified at once. - **A control a render removes takes its unwritten pick with it.** One that goes because the action itself replaces the page is written first. Following a link is not a handler of the page: it leaves the form, and a pick that was never written leaves with it — where a waiting input's text is still sent ahead of the navigation, because the browser holds it. - A pick that waits lives in the session. A reconnect to a new session — a restarted server — forgets it, where a waiting input keeps what was typed in the browser. A controlled input is not bound and none of this applies to it: `Input.Value(_filter).OnInput(v => _filter = v)` hears every keystroke, as before. ### The two modes are exclusive A control's value comes from exactly one place, and the step you open the chain with says which: | Opened with | Mode | Its steps | Compile, but do nothing here | | --- | --- | --- | --- | | `.Bind(() => model.Field)` | bound | `Validate`, `AfterBind` | `Checked`, `OnInput`, `OnChange` | | `.Value(v)` or `.Of()` | controlled | `Checked`, `OnInput`, `OnChange` | `Validate`, `AfterBind` | `Bind` and `Value` are the *openings* themselves, not steps you take later — taking one is what rules the other out, so neither appears again on the chain. `Of()` opens a controlled chain for a control you are giving no value at all; if you want to supply one, that is `.Value(v)`. Everything else — `Placeholder`, `Type`, `Required`, `Min`/`Max`, `OnFiles`, the whole `Class`/`Id`/ `Aria` element surface — belongs to neither and is reachable from both. **Choosing a mode is enforced by the type**: the two openings live on the control's entry and nowhere else, so taking one hands back the control and the other is not a member of it. ```csharp Input.Bind(() => _model.Name).Value(_typed) // ✗ no such step: Bind already answered this ``` The steps that FOLLOW an opening are not gated, and that is a deliberate trade. Each mode's steps used to be declared only on that mode, which took a `Bound`/`Controlled` type argument threaded through every generated signature to arrange — for a rule that only ever caught a property being set and then not read. So this compiles now, and does nothing: ```csharp Input.Bind(() => _model.Name).OnInput(v => _log = v) // compiles; the handler never runs ``` The reason it does nothing is that bound mode already owns those: it derives the rendered value (and a checkbox's `checked`) from the model and installs its own `oninput`/`onchange` write-back. Want a side effect on each bound write? That is what `AfterBind` is for. The openings themselves stay exclusive: `Input.Bind(…)` and `Input.Value(…)` both live on the chain's entry, so once you have taken one the other is not there to take. Beyond the constraint/affordance attributes shared with plain HTML (`Min`/`Max`/`Step`/`Pattern`/ `MaxLength`/`MinLength`/`Multiple`/`Accept`/`List`/`Autocomplete`/`Autofocus`), the core `Input` also carries the mobile & accessibility hints `InputMode` (on-screen keyboard), `EnterKeyHint` (action-key label), `Spellcheck` (the enumerated `spellcheck="true|false"`), `Capture` (camera/mic for a file input), and `DirName`. A control of your own forwards them the same way (see [building-form-controls.md](https://rask.sh/docs/guides/building-form-controls/)). > **Fractional numbers get `step="any"` automatically.** A `decimal`/`double`/`float`/`Half` binding > renders ``. Without it HTML's default is `step="1"`, so the browser's own > constraint validation rejects `42.50` and **refuses to fire submit** — silently, with nothing thrown and > no validation message, which reads as the form being broken. Integral types keep the implicit whole-number > constraint. An explicit `.Step(…)` always wins, and is worth setting for money (`.Step("0.01")` makes the > spinner step by cents). ### File inputs `InputType.File` turns an `` into a file picker. Instead of binding a value, hand it an `OnFiles` callback (a synchronous or an asynchronous handler) that receives the selected `IRaskFile`s (`Name`/`Size`/ `ContentType`/`OpenReadStream()`), and constrain the picker with `Accept`, `Multiple`, and `Capture`: ```csharp Input.Of().Type(InputType.File).Accept("image/*").Multiple() .OnFiles(async files => { foreach (var f in files) await Save(f); }) ``` Uploading the bytes (streaming to a server endpoint, size limits, progress) is covered end-to-end in [http-and-files.md](https://rask.sh/docs/guides/http-and-files/). ```csharp Input.Bind(() => _model.Subscribe) // bool → checkbox Input.Bind(() => _model.Age) // int → number Input.Bind(() => _model.StartDate) // DateOnly → date Select.Bind(() => _model.Favorite)[Option.Value("Red")["Red"], Option.Value("Blue")["Blue"]] Textarea.Bind(() => _model.Notes).Rows(3) ``` Those are the browser's own controls. An app normally writes the [UI kit](https://rask.sh/docs/guides/ui-kit/)'s, which bind the same way: `Ui.DatePicker` for a date, `Ui.TimePicker` for a time (the two side by side for a date and a time), `Ui.Select.Bind(…).Listbox[…]` for a choice and `Ui.Input` for text and numbers. ### Empty value handling When the user clears an input, `BindingHelpers.TrySetTyped` decides what the empty string maps to: | Property kind | Empty input becomes | |---|---| | `Nullable` value type (`int?`, `DateOnly?`, …) | `null` | | NRT-nullable reference type (`string?`) | `null` (detected via `NullabilityInfoContext`) | | Non-nullable value type (`int`, `DateOnly`, enum) | `default(T)` — so a number/date/enum input is clearable | | Non-nullable `string` | `""` (verbatim) | A value that fails to parse (`"1.5"` or `"99999999999"` into an `int`, a date half typed) leaves the model unchanged **and is not accepted in its place**: the field says what it could not read ("Enter a whole number."), ahead of "required" and of any rule, and the submit handler does not run until a value arrives that fits — see [what a number field says when it cannot read what was typed](https://rask.sh/docs/guides/forms-validation/#what-a-number-field-says-when-it-cannot-read-what-was-typed). **Controls over a value type bind its nullable too.** `Ui.Checkbox` and `Ui.Switch` are over `bool`, `Ui.Slider` over a number and `Ui.Calendar` over `DateOnly`, and each also binds the nullable form: `Ui.Checkbox.Bind(() => model.InStock)` compiles whether `InStock` is a `bool` or a `bool?`, which is what a [generated form model](https://rask.sh/docs/guides/data/#a-create-and-an-edit-form) holds. A `null` draws as the control's empty state (unchecked, no day picked, a slider at its lowest value), and a change writes a value. `Value` and `OnChange` stay over the plain type. The date controls go one further: `Ui.Calendar` binds a `DateOnly`, and behind Flux's mode steps a collection of days (`Ui.Calendar.Multiple.Bind(…)`) or a `UiDateRange` (`Ui.Calendar.Range.Bind(…)`); `Ui.DatePicker` a `DateOnly` or, as `Ui.DatePicker.Range`, a `UiDateRange`; and `Ui.TimePicker` a `TimeOnly?`, a `TimeOnly` or a collection of times ([UI kit](https://rask.sh/docs/guides/ui-kit/#calendar)). Every BCL [`IParsable`](https://learn.microsoft.com/dotnet/api/system.iparsable-1) type (numbers, `Guid`, `DateOnly`/`DateTime`/`TimeOnly`, `bool`, …) binds with no setup, and so does a **custom** `IParsable` value type under the default interpreter build. For a full [WASM AOT](https://rask.sh/docs/guides/aot/) build, register your custom form-field types once at startup with `RaskBinding.RegisterParsable()` — custom route/query param types are registered automatically by the generator. ### Binding lifecycle Each change handler runs in order: write the value, `NotifyFieldChanged`, run `AfterBind` (if supplied, only when a write actually happened), `NotifyFieldTouched`, then re-validate the field. When that happens is the control's [bind timing](#bind-timing): with the next action unless the chain says `.Live()`, `.Debounce(…)` or `.Blur()`. A text field sent at every keystroke (`.Debounce(TimeSpan.Zero)`) stays quiet until it is touched, then re-validates on every keystroke. `AfterBind` fires **after** the new value is written and before validators run — handy for dependent fields (pick a country, repopulate the city dropdown in the same render): ```csharp Select.Bind(() => _model.Country) .AfterBind(c => { _cities = Cities[c]; _model.City = _cities[0]; })[ /* options */ ] Select.Bind(() => _model.City)[_cities.Select(c => Option.Value(c)[c])] ``` It takes an asynchronous handler just as readily — one property, either shape — and awaits before the post-handler render, so a dependent async lookup (repopulate a dropdown from an API) surfaces its loading state on its own, with no manual `StateHasChanged()`: ### What a bind costs, and the one case worth changing `Bind(() => …)` takes an `Expression>`, and **the C# compiler builds that tree at the call site on every render**. Building it resolves a member token on the bound property's *declaring type*, and that cost scales with how many members the type has: | what you bind | B/render | | --- | --- | | `Input.Value(…)` — controlled, no bind at all | 1216 | | `Input.Bind(() => Model.Name)` — a plain model | 3041 | | `Input.Bind(() => Draft)` — a property on the **component** | 5011 | The third row is the surprise, and it is invisible at the call site: the two spellings look equally cheap. A component is a markup host, so the generator injects the chain entries into it — around 430 members — and binding a property *declared there* pays for resolving a token on a type that large. Binding the same value on a plain model does not. **For nearly every app this does not matter.** A form re-renders on interaction, not in a loop; a few kilobytes per render is well under the noise. Reach for the fix below only when a bound control is in something genuinely hot — a virtualized grid, a control that re-renders on every keystroke of a large document. **The fix is at the call site: hoist the expression into a field**, so it is built once instead of per render. ```csharp using System.Linq.Expressions; public sealed partial class Editor : Component { private readonly Model _model = new(); // Built once, in the constructor, rather than on every render. private readonly Expression> _name; public Editor() => _name = () => _model.Name; protected override Component Render() => Input.Bind(_name); } ``` The two rows converge once the tree stops being rebuilt: **2721 B/render** hoisted against a plain model, **2753 B** hoisted against a property on the component — so hoisting does not merely help the expensive shape, it erases the difference. What remains is the binding machinery (`FieldIdentifier`, validator registration, owner tracking), which is shared with the plain-model case. Every number on this page is pinned by `BuilderEntryAllocationPinTests`, so none of them can drift without a test going red. The other move is simply **to bind a plain model rather than a property on the component** (`() => _model.Name`, not `() => Draft`), which is what most code does already and costs 3041 B rather than 5011 B without any ceremony. > Why not fix this in the framework? Measured and ruled out in > [#803](https://github.com/pal-tamas/rask/issues/803): a Roslyn interceptor cannot help — an > interceptor must keep the intercepted method's signature (CS9144), and the lambda is converted to an > expression tree when the call is *bound*, before interception applies. Adding a `Func` overload > does not help either, because C# prefers the `Expression` one. What remains is making the injected > chain entries inheritable instead, which is a change to how every markup host is generated. --- ## 2. `Form.Model(…)` and the `EditContext` `Form.Model(model)` wraps the inputs and owns an `EditContext` — the per-field state store plus the validator pipeline. Bound inputs inside the form discover that context automatically. ```csharp Form.Model(_model).OnSubmit(m => Console.WriteLine(m.Username))[ Input.Bind(() => _model.Username), Button.Type(ButtonType.Submit)["Sign up"] ] ``` A field's rule is a step on its input — the value in, the messages that reject it out: ```csharp Input.Bind(() => _model.Username) .Validate(v => v.Length >= 3 ? [] : ["At least 3 characters."]) ``` A rule across fields goes on the form the same way, and either can be `async`: see [validation](https://rask.sh/docs/guides/forms-validation/). Submit runs every rule, marks every registered field touched, then routes: - valid → `OnSubmit` (or, if unset, `OnAnySubmit` with the raw `FormData`), - invalid → `OnInvalidSubmit`. `OnSubmit` / `OnInvalidSubmit` are one `Callback` each, so either takes a synchronous (`Action`) or an asynchronous (`Func`) handler — a bare lambda or a method group, no cast, no `…Async` twin. While a submit is in flight the form takes no second one, as Livewire's `wire:submit` does: at the press, before anything is sent, the runtime disables the form's submit buttons (a `