Browser Persistence with localStorage and sessionStorage

In the previous article we learned how to use a State Container to share data between pages. However, its content lives in memory: if we reload the application or the circuit ends, the data is lost.

To preserve part of that state, the browser offers two stores associated with the application’s origin:

From C# we access these APIs through JS interop. This implies they are not available during prerendering: we must wait until the component is interactive.

The Option You Should Not Use

In older articles you will find references to ProtectedBrowserStorage, which allowed storing data in localStorage or sessionStorage using ASP.NET Core Data Protection.

The important nuance is that the Microsoft.AspNetCore.ProtectedBrowserStorage package was experimental and not intended for production. Furthermore, current documentation keeps it as a historical reference for legacy applications, not as a recommendation for a modern Blazor application.

A Custom Service with JS Interop

We can encapsulate the JavaScript calls and serialization so that components do not repeat this logic:

using System.Text.Json;
using Microsoft.JSInterop;

public sealed class BrowserStorageService(IJSRuntime js)
{
    public async ValueTask SetLocalAsync<T>(string key, T value)
    {
        var json = JsonSerializer.Serialize(value);
        await js.InvokeVoidAsync("localStorage.setItem", key, json);
    }

    public async ValueTask<T?> GetLocalAsync<T>(string key)
    {
        var json = await js.InvokeAsync<string?>("localStorage.getItem", key);

        return json is null
            ? default
            : JsonSerializer.Deserialize<T>(json);
    }

    public ValueTask RemoveLocalAsync(string key) =>
        js.InvokeVoidAsync("localStorage.removeItem", key);
}

To work with sessionStorage, we can provide equivalent methods that invoke sessionStorage.setItem, sessionStorage.getItem, and sessionStorage.removeItem.

We register our service with the same scope as the UI state:

builder.Services.AddScoped<BrowserStorageService>();

Loading Data When the Component is Interactive

During prerendering, there is no connection to the browser APIs. OnAfterRenderAsync executes when the component can use JS interop:

@inject BrowserStorageService Storage

<button @onclick="GuardarCarrito">Save cart</button>

@if (!cargado)
{
    <p>Loading cart...</p>
}

@code {
    private List<Producto> carrito = [];
    private bool cargado;

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        if (!firstRender)
        {
            return;
        }

        carrito = await Storage.GetLocalAsync<List<Producto>>("mi-carrito") ?? [];
        cargado = true;
        StateHasChanged();
    }

    private Task GuardarCarrito() =>
        Storage.SetLocalAsync("mi-carrito", carrito).AsTask();
}

The explicit call to StateHasChanged is necessary because Blazor does not automatically re-render when a task started from OnAfterRenderAsync completes.

State Persistence Pattern

It is advisable that components do not depend directly on the persistence mechanism. We can combine it with the State Container from the previous article:

1. When the UI is already interactive, the state service loads data from the browser.
2. When modifying the state, it updates the memory and persists the change.

public sealed class CarritoService(BrowserStorageService storage)
{
    public List<Producto> Items { get; private set; } = [];

    public async Task InitializeAsync()
    {
        Items = await storage.GetLocalAsync<List<Producto>>("cart") ?? [];
    }

    public async Task AddItemAsync(Producto producto)
    {
        Items.Add(producto);
        await storage.SetLocalAsync("cart", Items);
    }
}

The component can call InitializeAsync in its first OnAfterRenderAsync, just like in the previous example.