[Preview 6] Blazor: document '@key' attribute

[ajaybhargavb]

While working on directive attribute documentation, I realized there was no documentation for the key attribute in blazor. More context here dotnet/aspnetcore#8232.

@danroth27 @SteveSandersonMS

[SteveSandersonMS]

Here's some proposed content. I think this should be added to the components page, probably right below capture references to components.

Is this satisfactory, @guardrex?

---

Using @key to control the preservation of elements and components

When you render a list of elements or components, and that list subsequently changes, Blazor's diffing algorithm needs to decide which of the previous elements/components can be retained, and how your model objects should map to each of them. Normally this process is automatic and can be ignored, but there are cases where you may want to control it in more detail.

Consider the following example:

@foreach (var person in People)
{
    <DetailsEditor Details="@person.Details" />
}

@code {
    [Parameter] IEnumerable<Person> People { get; set; }
}

If the contents of the People collection changes (for example, with entries being inserted/deleted or reordered), then when this component re-renders, the <DetailsEditor> components may change to receive different Details parameter values. This may cause more complex re-rendering than you expected, and in some cases can even lead to visible behavior differences, such as with element focus being lost.

You can take control over the mapping process by using the @key directive attribute. If you put a @key directive attribute on any element or component, the diffing algorithm will use this to guarantee preservation of elements or components based on that key. For example,

@foreach (var person in People)
{
    <DetailsEditor @key="@person" Details="@person.Details" />
}

@code {
    [Parameter] IEnumerable<Person> People { get; set; }
}

Now, when the People collection changes, the diffing algorithm retains the association between <DetailsEditor> instances and person instances:

• If a Person was deleted from the People list, then only the corresponding <DetailsEditor> instance will be removed from the UI. Others will be left unchanged.
• If a Person was inserted at some position in the list, then just one new <DetailsEditor> instance will be inserted at that corresponding position. Others will be left unchanged.
• If some Person entries were re-ordered, then the corresponding <DetailsEditor> instances will be preserved and re-ordered in the UI.

Altogether, this minimizes the complexity of re-rendering, and avoids potential issues with stateful parts of the DOM seeming to change (such as focus position).

Important: Keys are local to each container element or component. They are not compared globally across the document.

When to use @key

Typically, it makes sense to use @key whenever you a rendering a list (e.g., in a @foreach block) and you have a suitable value to define the @key.

You can also use @key as a way of forcing Blazor not to preserve a certain element or component subtree when something changes. For example:

<div @key="@currentPerson">
    ...some content that depends on @currentPerson...
</div>

In this example, if @currentPerson changes, then the @key will force Blazor to discard the entire <div> and its descendants, and rebuild that subtree within the UI with new elements and components. This can be useful if you need to guarantee that no UI state is preserved when @currentPerson changes.

When not to use @key

There is some extra cost within diffing if you use @key. It's not a large cost, but you should only specify @key if you actually benefit from controlling element/component preservation rules.

Even if you don't use @key, Blazor still preserves child element and component instances as much as possible. The only advantage to using @key is that you get to control how model instances are mapped to the preserved component instances, instead of the mapping being selected by the diffing algorithm.

What values to use for @key

Generally it makes sense to supply one of the following kinds of value for @key:

• Model object instances (e.g., a Person instance as in the above example). This ensures preservation based on object reference equality.
• Unique identifiers (e.g., primary key values of type int, string, or Guid)

Try to avoid supplying any type of value that can clash unexpectedly. For example, if you supply @key="@someObject.GetHashCode()", then you may have unexpected clashes (the hash codes of entirely unrelated objects can be the same). If you render clashing @key values within the same parent, they will not be honored.

[guardrex]

Perfect ... I'll take it from here.