blazor-component-design

Blazor Component Design

Design and implement Blazor components following project conventions.

Workflow

1. Define component parameters — identify inputs, event callbacks, and cascading values
2. Implement render logic — keep .razor lean, extract complex logic to code-behind
3. Wire parent-child communication — use EventCallback<T> for upward data flow
4. Handle lifecycle — implement OnInitializedAsync, OnParametersSetAsync as needed
5. Optimize rendering — add @key for lists, ShouldRender() for expensive components

Component Structure

@* ItemCard.razor *@
<div class="item-card" @key="Item.Id">
    <h3>@Item.Name</h3>
    <p>@Item.Description</p>
    <button @onclick="HandleSelect">Select</button>
</div>

@code {
    [Parameter, EditorRequired]
    public ItemDto Item { get; set; } = default!;

    [Parameter]
    public EventCallback<ItemDto> OnSelected { get; set; }

    private async Task HandleSelect() => await OnSelected.InvokeAsync(Item);
}

Code-Behind Pattern

// ItemList.razor.cs
public partial class ItemList : ComponentBase, IDisposable
{
    [Inject] private IItemService ItemService { get; set; } = default!;
    [Parameter] public string? FilterCategory { get; set; }

    private List<ItemDto> _items = new();

    protected override async Task OnParametersSetAsync()
    {
        _items = await ItemService.GetItemsAsync(FilterCategory);
    }

    public void Dispose() { /* unsubscribe from events */ }
}

Best Practices

• Parameters over cascading values — explicit data flow is easier to trace and debug
• EventCallback<T> for parent-child communication — never mutate parent state directly
• Code-behind for components with logic — keeps .razor focused on markup
• @key directive on list items — prevents DOM thrashing on re-renders
• IDisposable when subscribing to events, timers, or injected services with subscriptions
• [EditorRequired] on mandatory parameters — catches missing bindings at compile time