What they are
In a .razor file, an attribute whose name starts with @ is a directive attribute: an instruction to the compiler about the element or component it is on. The name runs to white space, =, > or /> and may contain a : followed by a modifier (@bind:event) and, for components, a hyphen and a parameter name (@bind-Value, @bind-Value:after). The value is C#: a method name, a lambda, or @(expression). Names are case-sensitive: @Bind and @bind:Event are not directive attributes.
In a .cshtml view an @ at the start of an attribute name is not this: it starts C# (<input @(ok ? "checked" : "") />), and @@ there escapes the at sign.
<input @bind="name" @bind:event="oninput" @bind:after="Save" />
<button @onclick="() => count++" @onclick:preventDefault @onclick:stopPropagation>+</button>
<li @key="item.Id" @ref="row">@item.Name</li>
<Child @attributes="extra" @rendermode="InteractiveServer" />
<EditForm Model="m" @formname="signup" OnValidSubmit="Go" />
The attributes
| Attribute | On | Meaning |
|---|---|---|
@bind | element | Two-way binding of the element's value to a C# field or property. The event is onchange unless @bind:event says otherwise. (For some input types, such as checkbox, the bound attribute is checked.) |
@bind-PARAMETER | component | Two-way binding to a component parameter: @bind-Value="x" sets Value and listens to the callback ValueChanged. |
@bind:event, @bind-PARAMETER:event | both | The DOM event that updates the value, such as oninput. |
@bind:format, @bind-PARAMETER:format | both | A format string for converting the value to text (dates, numbers). |
@bind:culture, @bind-PARAMETER:culture | both | A CultureInfo for parsing and formatting. |
@bind:after, @bind-PARAMETER:after | both | A method (sync or async) called after the value has been updated. Not an EventCallback. |
@bind:get and @bind:set, @bind-PARAMETER:get and :set | both | Binding as a pair: :get is the value, :set a callback that receives the new one (so it can change it before it is applied). The two are always used together. |
@onevent | element, component parameter | An event handler. The value is a method, a lambda, or @(...). See the list below. |
@onevent:preventDefault | element | Prevents the default action of the event. Without a value it means true; a boolean expression is also allowed. |
@onevent:stopPropagation | element | Stops the event bubbling. |
@key | element, component | A value the diff algorithm uses to keep the element or component matched to the same data when a list changes. |
@ref | element, component | Captures a reference: a field of type ElementReference for an element, or the component's type for a component. |
@attributes | element, component | Splats a dictionary of attributes (IEnumerable<KeyValuePair<string, object>>) onto the element or component; the ones the component does not declare go to its captured unmatched parameters. |
@rendermode | component | The render mode of one component instance: @rendermode="InteractiveServer". (The directive of the same name sets it for the component's own file.) |
@formname | form, EditForm | A unique name for the form, used to route a posted form to its handler. |
A directive attribute may be written without = and a value where the modifier is a flag, such as @onclick:preventDefault.
Event names
An element event attribute is @on plus the DOM event name, and its handler receives the event arguments type shown. Ninety-six events are built in (the list is the [EventHandler] attributes of the ASP.NET Core web components library); a component can declare more.
| Arguments | Attributes |
|---|---|
MouseEventArgs | onclick ondblclick oncontextmenu onmousedown onmouseup onmousemove onmouseover onmouseout onmouseenter onmouseleave |
WheelEventArgs | onwheel onmousewheel |
KeyboardEventArgs | onkeydown onkeyup onkeypress |
ChangeEventArgs | onchange oninput |
FocusEventArgs | onfocus onblur onfocusin onfocusout |
DragEventArgs | ondrag ondragend ondragenter ondragleave ondragover ondragstart ondrop |
ClipboardEventArgs | oncopy oncut onpaste |
TouchEventArgs | ontouchstart ontouchend ontouchmove ontouchcancel ontouchenter ontouchleave |
PointerEventArgs | onpointerdown onpointerup onpointermove onpointerover onpointerout onpointerenter onpointerleave onpointercancel ongotpointercapture onlostpointercapture |
ProgressEventArgs | onloadstart onprogress onloadend onload onabort ontimeout |
ErrorEventArgs | onerror |
EventArgs | onsubmit onreset oninvalid onselect onselectstart onselectionchange onscroll ontoggle oncancel onclose onbeforecopy onbeforecut onbeforepaste onactivate onbeforeactivate onbeforedeactivate ondeactivate onfullscreenchange onfullscreenerror onpointerlockchange onpointerlockerror onreadystatechange oncanplay oncanplaythrough oncuechange ondurationchange onemptied onended onloadeddata onloadedmetadata onpause onplay onplaying onratechange onseeked onseeking onstalled onstop onsuspend ontimeupdate onvolumechange onwaiting |
An event attribute on a component is just a parameter of type EventCallback that happens to be named that way; it is not special to the compiler.
In the viewer
Each directive attribute name is coloured as a directive and its value as C#, and each one is listed in the Outline tab with the element it is on. The scanner recognises any attribute name that starts with @ in a .razor file; it does not check the name against the lists above.