Binding
A binding ties a component property to a location in the controller's object graph, addressed by a
RecursivePath. This page covers how to write a path, which method binds it, and what happens when the
value it resolves to is missing or invalid.
Paths
A RecursivePath is an immutable list of segments: a property name, an index ([0]), or a key
(["abc"] or the bare [abc], both parsed the same way when the token is not an integer). ToString()
renders the grammar and RecursivePath.Parse(path) reads it back:
Lines[0].Price
An index or a key is read inside a row's item: bound Relative in an order's row template, the path above reads that order's
first line. Read from the controller, before any row (BindTitle("Orders[0].Total")), it is refused when the view compiles —
one element per row is an item template (Scopes, below), whose rows each read their own item.
Every Bind* method comes in a typed expression overload alongside its string one — the expression is
translated to a RecursivePath once when the view builds (RecursivePath.FromExpression), supporting nested
members, indexers, captured values and casts, while nameof works for a single property:
new TextComponent().BindTitle<CounterController>(c => c.Count)
new TextComponent().BindTitle(nameof(CounterController.Count))
Bind* vs the raw Bind
A bindable property generates its own Bind<Name>(string path, UIBindingScope scope = ..., UIBindingMode mode = ..., bool optional = false) and Bind<Name><TSource>(Expression<Func<TSource, object?>> path, UIBindingScope scope = ..., UIBindingMode mode = ..., bool optional = false) — the defaults come from how the property was declared (see Modes, below). There is also a raw
entry point every component inherits:
public TComponent Bind(UIProperty property, string path, UIBindingScope scope = UIBindingScope.Root, UIBindingMode? mode = null, bool optional = false)
public TComponent Bind<TSource>(UIProperty property, Expression<Func<TSource, object?>> path, UIBindingScope scope = UIBindingScope.Root, UIBindingMode? mode = null, bool optional = false)
Reach for the raw Bind only when binding by property key at runtime (a template that binds by
IVisualComponent property object rather than by name). With no mode it takes the property's own default, as the
generated method does — a field's Value binds TwoWay, a text's Title OneWay.
Bind throws at view-compile time if the property is not registered for the component, is not bindable
(IsBindable = false), or does not support the requested mode.
Mistakes the compiler catches
A view is compiled with its controller's type — at startup, unless the route is Lazy — and these mistakes are
caught there rather than in front of a user:
One element of a controller's collection by a fixed index or key (
BindContext("Phases[0]"),BindTitle("Orders[\"o1\"].Total")) fails the compile with the component and the path named; a row template addresses one element per row.A command the controller does not declare (
OnClick("Sav")) fails the compile with the component, the event and the controller named.A bound path the controller's types do not have (
BindTitle("Titel")) is a warning in the log, whatever the scope: aRelativepath inside an item template is checked through the collection's element type. A binding markedoptional, a path through anobject, and a property only a derived item type declares are not judged.A path the server cannot read warns too: a controller property that is no
[RecursiveMember](a computedHeader => …, a plain auto-property) or a step through a type that is noRecursiveObservable(Owner.NamewhereOwneris a record) resolves to nothing on the server. A row's own fields travel to the page whole, so the check stops at the first row.A row's
Rootbinding its item has too (BindTitle(nameof(Message.Title))in a row, the controller holding aTitle) warns: every row would show the controller's one value. Bind itRelative.A declared list's row binding what none of its items has (
SetItems(...)with a template bindingCaption) warns, as a controller's list does; aBindContextpath is checked as a property's.A form nothing submits fails the compile: a field bound
OnSubmit, or aSubmitOnEnterarea, whoseFormIdno button'sOnSubmit(formId, …)submits, nor a field's own submitting event (a code field's save,IFormSubmittingComponent). A view with a button whose submit form id is bound is not checked: that form is the page's to make.Inline rename without a writable
RenamedTitlefails the compile: enabling inline rename (SetRenamable(true)/BindRenamable,.Editable,OnRename*,OnItemRename*,UITabMenuEntries.Rename, orRenameItemEffect) requires a writable (TwoWay,OneWayToSource, orOnSubmit)BindRenamedTitleon the renamed component or item template.
Each warning carries its kind (UICompileWarning.Kind): a binding or a path that names nothing is UnresolvedBinding, which a
test page refuses (see testing); a Root binding a row's item shadows, an argument no parameter takes and a
selection binding its mode never reads are Advisory, logged only. An argument the framework adds itself (a drop's drop, an
edited row's id) never warns. A page in Development writes every warning to its browser console.
Scopes
UIBindingScope says where a path is resolved from:
| Value | Resolves from |
|---|---|
Relative |
The component's own context — inside an item template, the row being rendered. Pass it explicitly there; only a row's own properties default to it: an item's abilities (CanSelect, CanDrag, CanRemove, CanRename, CanShowContextMenu), a tree node's (ParentId, HasChildren, IsFolder, Expanded, DropTarget), a tab's Order and Pinned, and IRenamableComponent.RenamedTitle (a text's, a tree node's or a tab's). |
Parent |
One level up from the context this component belongs to — not one visual hop. A plain visual child only inherits its context, so Parent on a component with no context of its own lands one level above its nearest context-defining ancestor. |
Root |
The controller root. This is what a raw Bind and every generated Bind* but the row's own above default to — inside an item template this is almost never what is meant. |
A nested items example: an items view binds its rows from the controller, and its row template — one component tree, compiled once and reused for every row — binds relative to whichever row it is currently rendering:
new ItemsViewComponent()
.BindItems(nameof(ContextMenuGroupContext.Deploys), UIBindingScope.Relative)
.SetTemplate(new ActionComponent()
.BindTitle(nameof(DemoDeploymentRow.Service), UIBindingScope.Relative)
)
Inside a template a plain visual child inherits its enclosing row's context, so Relative there resolves
against the row rather than the view root — the source of the "almost never Root" rule above. Nesting one
more items view inside a row template compounds the same rule: its own Relative binding appends to the
row's path, producing something like "Groups[].SubItems" for the inner collection.
Modes
UIBindingMode:
| Value | Direction |
|---|---|
OneWay |
Source to target only. |
TwoWay |
Both directions. |
OneWayToSource |
Target to source only — the initial change set does not carry this value, so nothing but the renderer ever writes it; use it for state the server only stores. |
OnSubmit |
Target-to-source updates are buffered on the client until an explicit submit (ButtonComponent.OnSubmit(formId, command)), then flushed before the command runs. Unlike OneWayToSource, the initial change set does carry this value. The field needs a form id (see A form, below). |
A property must declare the matching BindingCapabilities (UIBindingCapabilities: SourceToTarget,
TargetToSource, SubmitBufferedTargetToSource, a [Flags] enum) for a mode to be accepted —
IInputComponent.Value declares all three plus DefaultBindingMode = UIBindingMode.TwoWay, which is why
BindValue defaults to two-way without saying so.
What a null value renders
A binding that resolves to null does not clear the property — it falls back to the value the
component was authored with (Set*), or, absent that, the property's registered default. A controller
holding null for a bound property therefore renders exactly what the same component renders unbound. This
is also why a property both Set* and Bind*-ed comes back to the set value rather than to nothing when
the bound value is missing.
Static-only properties
A property declared IsBindable = false, GenerateBinder = false generates no Bind<Name> method, and
Bind(UIProperty, …) refuses it at compile time with a thrown error — never a silent no-op. Reach for this
when a property is genuinely render-time-only (read once to build a picker, for instance); it is not a
workaround for "I don't want this bound yet."
Responsive values
Any UIResponsive<T>? property gets a convenience Set* overload alongside its plain one:
public TComponent SetWidth(UILayoutLength value, UILayoutLength? sm = null, UILayoutLength? md = null, UILayoutLength? xl = null, UILayoutLength? xxl = null)
sm, md, xl, xxl are the breakpoint tiers; an unset tier falls back to the next narrower one that is
set, down to the base value (mobile-first). SetPlacement on every visual component follows the same shape
(see views, placement grid).
BindContext
BindContext(path, scope) binds the component's context rather than one of its properties — the base
path every relative binding and action argument inside this component (and its descendants, if it is a
container) resolves against. It names a member or an object, not one element of a collection: one element per row is an
item template, whose rows each take their item as context.
public virtual TComponent BindContext(string path, UIBindingScope scope = UIBindingScope.Root)
public virtual TComponent BindContext<TSource>(Expression<Func<TSource, object?>> path, UIBindingScope scope = UIBindingScope.Root)
public virtual TComponent BindContext(RecursivePath path, UIBindingScope scope = UIBindingScope.Root)
Two-way sync
A two-way-bound value syncs on the native change event, not input — fewer round-trips — except where a text input, a text
area or a search sets SetDebounceMilliseconds: it commits while typing, that long after the last keystroke. The property
still needs its capability declared correctly (see Modes, above) or the client's write is silently dropped
by the runtime rather than applied.
Validation on inputs
An input's validation message comes from up to four sources, and the strongest one shown wins:
Client rules, added fluently:
new TextInputComponent() .Required("Name is required.") .Regex(@"^\S+@\S+$", "Enter a valid email.", trigger: UIValidationTrigger.Blur, severity: UIValidationSeverity.Warning)public static TComponent Required<TComponent>(this TComponent input, string message, UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error) public static TComponent Regex<TComponent>(this TComponent input, string pattern, string message, UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error) public static TComponent RegexEach<TComponent>(this TComponent input, string pattern, string message, UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error) public static TComponent Validate<TComponent>(this TComponent input, UIValidationTrigger trigger, UIComparisonOperator @operator, object? value, string message, UIValidationSeverity severity = UIValidationSeverity.Error)RegexEachis for a list value: every item must match — a multi-select's each key, and a tag typed into one taking free text is refused before it becomes a chip.A rule may compare with another field's value instead of a fixed one — "Password again" equal to "New password":
TextInputComponent password = new TextInputComponent().SetType(UITextInputType.Password); new TextInputComponent() .SetType(UITextInputType.Password) .ValidateAgainst(password, UIComparisonOperator.Equal, "The passwords differ.")public static TComponent ValidateAgainst<TComponent>(this TComponent input, UIComponentReference other, UIComparisonOperator @operator, string message, UIValidationTrigger trigger = UIValidationTrigger.Change, UIValidationSeverity severity = UIValidationSeverity.Error)UIComponentReferenceconverts implicitly from either anIInputComponent/IVisualComponentinstance or a stringcomponentId(andValidationInto,FilterByandSortByaccept the target component instance directly the same way).It is judged in the browser as either field changes: a reader who types the second field first and then changes the first sees the second judged again. The field compared with is another input, read as its own rules read it, standing in the same row as the judged field or in none; a comparison names it (
Equal,Greater…), neverRequiredor a pattern. The server does not judge it again, as it judges no field's rules — a check the data depends on stays the command's.Every rule but
Requiredpasses an empty value, so a field left empty — tabbed through, never typed in — says only that it is required, and an optional field's pattern judges only what was typed. A rule that must refuse an empty field goes withRequired; a toggle'sfalseis a value, which a rule may judge.UIValidationTriggerisChange(default),Blur, orSubmit.UIValidationSeverityisError(default — stops a submit and draws the required marker when it is aRequiredrule),Warning, orInfo; each colours the field's edge in its own colour. Each takes its message as aUIPhrasetoo, a key with arguments —.Regex(@"^.{0,40}$", UIPhrase.Of("form.max", ("max", 40)))— and a string message is translated as a plain value is (see Localization).The controller, through the bindable
Validationproperty everyIInputComponenthas:new TextInputComponent().BindValidation(nameof(FormController.NameValidation))public static UIValidationMessage Error(string message) public static UIValidationMessage Warning(string message) public static UIValidationMessage Info(string message) // and the same three taking a UIPhrasenullmeans no message. A controller's own message never blocks a submit — the controller wrote it and judges the value again on the next attempt; clearing it is the controller's job.The runtime, when it refuses a value the controller could not take.
The field's bounds. A number, date or time typed past its
MinorMaxstays as typed and is refused in words — "At most 10.", "Not after 30.09.2026." — never pulled back to the bound and never sent, so the controller keeps the last value it took. An emptied field is no value, which an optional one takes.
Only an error from a client rule, the runtime or a bound stops OnSubmit(formId, command) from dispatching — the
controller's own error does not gate the press.
A form
A form is not a component: it is a string id that a set of fields and a submit button share. SetFormId (or
BindFormId) puts a field in it — any IInputComponent has FormId — and ButtonComponent.OnSubmit(formId, command) makes a button its submit button (OnSubmitShowingLoading(formId, command) also shows it busy for the command's round
trip):
new StackPanelComponent()
.SetSpacing(12)
.AddChild(new TextInputComponent()
.SetTitle("Email")
.SetFormId(ProfileController.ProfileForm)
.BindValue(nameof(ProfileController.Email), mode: UIBindingMode.OnSubmit)
.Required("An email is required.", UIValidationTrigger.Submit)
.Regex(@"^[^@\s]+@[^@\s]+\.[^@\s]+$", "That does not look like an email address.", UIValidationTrigger.Blur)
)
.AddChild(new TextInputComponent()
.SetTitle("Display name")
.SetFormId(ProfileController.ProfileForm)
.BindValue(nameof(ProfileController.DisplayName))
)
.AddChild(new ButtonComponent()
.SetTitle("Save")
.SetVariant(UIButtonVariant.Primary)
.OnSubmit(ProfileController.ProfileForm, nameof(ProfileController.Save))
)
.AddChild(new ButtonComponent()
.SetTitle("Discard")
.SetVariant(UIButtonVariant.Outline)
.OnClick(nameof(ProfileController.Discard))
)
public const string ProfileForm = "profile";
[UICommand]
public static UICommandResult Discard()
=> UICommandResult.Ok([new DiscardFormEffect(ProfileForm)]);
What the form id does:
- It scopes a submit's validation. Pressing the submit button runs every
Submit-trigger rule of the form's fields, then dispatches the command only if no field of the form holds an error — from those rules, from aChangeorBlurrule failing at that moment, or from the runtime. AWarningorInfosays its piece and lets the press through, and so does the controller's own message. - It is what an
OnSubmitfield waits for. A value boundOnSubmitstays in the browser until its form is submitted, and is sent after validation and before the command, so the command reads it already written. While the field holds an unsent edit, a value the server pushes does not overwrite it. A field boundOnSubmitwith no form id fails the view's compile — its value could never be sent. - It lets Enter submit. Enter in a single-line field of a form presses the form's submit button, after the
field has let go of its value. In a text area Enter breaks the line, unless the area says
SetSubmitOnEnter(): then Enter commits its value and presses the form's button while the focus stays in the area, ready for the next message, and Shift+Enter breaks the line — a message the same as the last one is sent again once a push has cleared the area; an Enter that ends an input method's composition sends nothing. A text area that submits on Enter with no form id fails the view's compile. - It is a form to the browser too. The page carries a hidden
<form>per form id, and the form's fields and submit button join it (form="ui-form-<id>"), so a password manager and autofill read each form apart: a sign-in's name and password share their form id, and a password that is no one's login (a token, a new password on a settings page) gets one of its own. A field with no form id stands in the page's own form. The browser's form submits nothing — everything above goes by the form id.
A field that takes one entry after another — a line added to a checklist, a label typed and added — needs no form: OnEnter
on a text input or a text area runs a command on Enter. Enter alone commits the value first and the command waits for its
answer, so it reads the value already written (and runs nothing for a value the controller refused); the field keeps the focus
for the next entry and presses no form's button. In a text area Shift+Enter still breaks the line, and a chord keeps a field's
ordinary rule. A held key runs it once, and a read-only, disabled or loading field runs nothing. In a row's template the row's
key travels as any command's argument does:
new TextInputComponent()
.SetPlaceholder("Add an item")
.BindValue(nameof(ChecklistItem.Draft), UIBindingScope.Relative)
.OnEnter(nameof(ChecklistController.AddItem), UIAction.ArgCurrentItemKey("id"))
A text area with both OnEnter and SubmitOnEnter fails the view's compile: Enter does one of them.
Escape leaves a field and commits what was typed in it. A field opened for a change — a message edited in the composer, a
row's text edited in place — says OnEscape instead, and Escape becomes its cancel: the field goes back to the value it last
committed (the one it was focused with, an earlier commit's, or one the server pushed since), what was typed after it is not
sent and raises no change — a debounced field's waiting commit is dropped, not flushed — the field lets go of the focus as
Escape always does, and then the command runs, with the row's key in a row's template, as OnEnter's does. A dialog or a
popup the field stands in leaves that Escape to it, and the next one closes them. A held key runs it once; a read-only,
disabled or loading field keeps the ordinary Escape and runs nothing. OnEscapeLiteral takes literal arguments.
new TextAreaComponent(ChatController.ComposerId)
.BindValue(nameof(ChatController.Draft))
.SetSubmitOnEnter()
.SetFormId(ChatController.ChatForm)
.OnEscape(nameof(ChatController.CancelEditAsync))
A form can mix modes: a TwoWay field (the display name above) sends each change as it happens and still counts
in the form's validation, while an OnSubmit field (the email) reaches the controller only with the submit — the
shape for a value that must not be half-written, or whose every change would start work on the server.
DiscardFormEffect(formId), returned from a command, drops the form's unsent edits: every OnSubmit field of the
form shows the value the server holds again. What the page's rules, the bounds and the runtime said of every field of the form
goes with them, changed or not, and the form stands as unvisited; the controller's bound message and a package's mark stay. A
TwoWay field has nothing unsent to drop. The discard button is an
ordinary OnClick — an OnSubmit one would send the edits before the command could throw them away.
A field's caption row is one caption line: a badge in it is centred on that line rather than growing the row, and a long
caption ends in an ellipsis rather than wrapping its required mark. SetHelp(help) on any input fills its caption's badge: the
help glyph alone, a UIBadgeVariant.Plain badge (no ground, in the muted ink, coming up to the text's ink under the pointer), with
the words — a text, a key or a UIPhrase — as the badge's tooltip, translated as a badge's tooltip is; a blank text is refused.
It sits where the input's badge sits: trailing at the caption row's end, unless
SetBadgePlacement(UITextBadgePlacement.Inline) puts it beside the words, and beside a checkbox's or a switch's label. The
badge is no tab stop: its words are the field control's accessible description, so a reader tabbing in hears them with the
field, and the pointer's hover shows them; in a caption outside the field's box a press or a touch shows them too, the next
press, on it or elsewhere, hides them, and a press on it never ticks the box around it:
new TextInputComponent()
.SetTitle("Display name")
.SetHelp("Shown beside your messages; your sign-in name stays private.")
.BindValue(nameof(ProfileController.DisplayName))
A text input and a text area carry buttons of the author's at either end — AddLeadingAction and AddTrailingAction, as many
as wanted, in the order added (on a text input SetTrailingAction puts one in place of all). A text input's stand in its row; a text area's
stand beside its text on the bottom line, outside its scroll, and the text reaches the buttons after it in the tab order. A
split button stands among them as compact as a plain one. Each also takes a FlyoutComponent: its anchor, which must be a
button, stands with the others and its panel opens from it — an emoji panel, a list of snippets; a flyout whose anchor is no
button is refused where it is added. On a select, search or multi-select, trailing actions stand inside the field before its rightmost divided chevron cell. Above the field, any input may carry compact actions on its 16 px caption line via SetHeaderAction / SetHeaderActions without raising the title or pushing the field box down, and a TextAreaComponent or CodeInputComponent configured with SetExpandable(...) adds a full-height modal expand mode (with separate inline and dialog parameters, also triggerable via ExpandFieldEffect).
SetAutoGrow(maxRows) makes a text area grow with its text from its Rows to maxRows lines, then scroll. Together they are a
chat's composer:
new TextAreaComponent("composer")
.SetPlaceholder("Write a message")
.SetRows(1)
.SetAutoGrow(6)
.SetSubmitOnEnter()
.SetFormId(ChatController.ChatForm)
.BindValue(nameof(ChatController.Draft))
.AddLeadingAction(UIIconButtons.Attach().OnClick(nameof(ChatController.Attach)))
.AddTrailingAction(UIIconButtons.Send().OnSubmit(ChatController.ChatForm, nameof(ChatController.Send)))
UIForm.Composer(textArea, attachments?, banners) wraps that composer text area in a calm SurfaceComponent (SetWindowFoot, no border or focus halo) with an optional shelf FileInputComponent wired to accept file drops across the panel and any quote banners above the field. Both TextInputComponent and TextAreaComponent also support inline trigger suggestions (@, /) via AddTrigger, SetTriggerItems/BindTriggerItems (UITextTriggerItem), OnTriggerSearch, OnTriggerSelect, and OnTriggerClick: typing a trigger character opens a suggestion popup at the caret (stepping into a second-level category or inserting a leaf token), and completed trigger tokens render as interactive inline pills that delete whole on Backspace/Delete and raise OnTriggerClick when clicked.
InsertTextEffect puts text at a field's caret from elsewhere, in place of its selection, as typing would — the caret after it,
the field's own undo holding it, its binding and validation following (see interactions and effects).
The field keeps its selection while the focus is in a panel beside it, so an emoji panel's tile inserts where the reader stopped:
new ButtonComponent()
.SetTitle(emoji)
.InteractOn("click", InsertTextEffect.Literal("composer", emoji))
A read-only or disabled field takes nothing, and a text longer than the room the field's MaxLength leaves is refused whole
rather than cut.
Where to go next
- Views for the placement grid and the fluent style
Bind*is part of. - Controllers for the paths
[RecursiveMember]properties expose. - Interactions and effects for interactions, which write a property directly rather than through a binding.