Blazored.LocalStorage 4.5.0

Prefix Reserved
dotnet add package Blazored.LocalStorage --version 4.5.0                
NuGet\Install-Package Blazored.LocalStorage -Version 4.5.0                
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="Blazored.LocalStorage" Version="4.5.0" />                
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add Blazored.LocalStorage --version 4.5.0                
#r "nuget: Blazored.LocalStorage, 4.5.0"                
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install Blazored.LocalStorage as a Cake Addin
#addin nuget:?package=Blazored.LocalStorage&version=4.5.0

// Install Blazored.LocalStorage as a Cake Tool
#tool nuget:?package=Blazored.LocalStorage&version=4.5.0                

Nuget version Nuget downloads Build & Test Main

Blazored LocalStorage

Blazored LocalStorage is a library that provides access to the browsers local storage APIs for Blazor applications. An additional benefit of using this library is that it will handle serializing and deserializing values when saving or retrieving them.

Breaking Changes (v3 > v4)

JsonSerializerOptions

From v4 onwards we use the default the JsonSerializerOptions for System.Text.Json instead of using custom ones. This will cause values saved to local storage with v3 to break things. To retain the old settings use the following configuration when adding Blazored LocalStorage to the DI container:

builder.Services.AddBlazoredLocalStorage(config =>
{
    config.JsonSerializerOptions.DictionaryKeyPolicy = JsonNamingPolicy.CamelCase;
    config.JsonSerializerOptions.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    config.JsonSerializerOptions.IgnoreReadOnlyProperties = true;
    config.JsonSerializerOptions.PropertyNameCaseInsensitive = true;
    config.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    config.JsonSerializerOptions.ReadCommentHandling = JsonCommentHandling.Skip;
    config.JsonSerializerOptions.WriteIndented = false;
});

SetItem[Async] method now serializes string values

Prior to v4 we bypassed the serialization of string values as it seemed a pointless as string can be stored directly. However, this led to some edge cases where nullable strings were being saved as the string "null". Then when retrieved, instead of being null the value was "null". By serializing strings this issue is taken care of. For those who wish to save raw string values, a new method SetValueAsString[Async] is available. This will save a string value without attempting to serialize it and will throw an exception if a null string is attempted to be saved.

Installing

To install the package add the following line to you csproj file replacing x.x.x with the latest version number (found at the top of this file):

<PackageReference Include="Blazored.LocalStorage" Version="x.x.x" />

You can also install via the .NET CLI with the following command:

dotnet add package Blazored.LocalStorage

If you're using Visual Studio you can also install via the built in NuGet package manager.

Setup

You will need to register the local storage services with the service collection in your Startup.cs file in Blazor Server.

public void ConfigureServices(IServiceCollection services)
{
    services.AddBlazoredLocalStorage();
}

Or in your Program.cs file in Blazor WebAssembly.

public static async Task Main(string[] args)
{
    var builder = WebAssemblyHostBuilder.CreateDefault(args);
    builder.RootComponents.Add<App>("app");

    builder.Services.AddBlazoredLocalStorage();

    await builder.Build().RunAsync();
}

Registering services as Singleton - Blazor WebAssembly ONLY

99% of developers will want to register Blazored LocalStorage using the method described above. However, in some very specific scenarios developer may have a need to register services as Singleton as apposed to Scoped. This is possible by using the following method:

builder.Services.AddBlazoredLocalStorageAsSingleton();

This method will not work with Blazor Server applications as Blazor's JS interop services are registered as Scoped and cannot be injected into Singletons.

Usage (Blazor WebAssembly)

To use Blazored.LocalStorage in Blazor WebAssembly, inject the ILocalStorageService per the example below.

@inject Blazored.LocalStorage.ILocalStorageService localStorage

@code {

    protected override async Task OnInitializedAsync()
    {
        await localStorage.SetItemAsync("name", "John Smith");
        var name = await localStorage.GetItemAsync<string>("name");
    }

}

With Blazor WebAssembly you also have the option of a synchronous API, if your use case requires it. You can swap the ILocalStorageService for ISyncLocalStorageService which allows you to avoid use of async/await. For either interface, the method names are the same.

@inject Blazored.LocalStorage.ISyncLocalStorageService localStorage

@code {

    protected override void OnInitialized()
    {
        localStorage.SetItem("name", "John Smith");
        var name = localStorage.GetItem<string>("name");
    }

}

Usage (Blazor Server)

NOTE: Due to pre-rendering in Blazor Server you can't perform any JS interop until the OnAfterRender lifecycle method.

@inject Blazored.LocalStorage.ILocalStorageService localStorage

@code {

    protected override async Task OnAfterRenderAsync(bool firstRender)
    {
        await localStorage.SetItemAsync("name", "John Smith");
        var name = await localStorage.GetItemAsync<string>("name");
    }

}

The APIs available are:

  • asynchronous via ILocalStorageService:

    • SetItemAsync()
    • SetItemAsStringAsync()
    • GetItemAsync()
    • GetItemAsStringAsync()
    • RemoveItemAsync()
    • ClearAsync()
    • LengthAsync()
    • KeyAsync()
    • ContainKeyAsync()
  • synchronous via ISyncLocalStorageService (Synchronous methods are only available in Blazor WebAssembly):

    • SetItem()
    • SetItemAsString()
    • GetItem()
    • GetItemAsString()
    • RemoveItem()
    • Clear()
    • Length()
    • Key()
    • ContainKey()

Note: Blazored.LocalStorage methods will handle the serialisation and de-serialisation of the data for you, the exceptions are the SetItemAsString[Async] and GetItemAsString[Async] methods which will save and return raw string values from local storage.

Configuring JSON Serializer Options

You can configure the options for the default serializer (System.Text.Json) when calling the AddBlazoredLocalStorage method to register services.

public static async Task Main(string[] args)
{
    var builder = WebAssemblyHostBuilder.CreateDefault(args);
    builder.RootComponents.Add<App>("app");

    builder.Services.AddBlazoredLocalStorage(config =>
        config.JsonSerializerOptions.WriteIndented = true
    );

    await builder.Build().RunAsync();
}

Using a custom JSON serializer

By default, the library uses System.Text.Json. If you prefer to use a different JSON library for serialization--or if you want to add some custom logic when serializing or deserializing--you can provide your own serializer which implements the Blazored.LocalStorage.Serialization.IJsonSerializer interface.

To register your own serializer in place of the default one, you can do the following:

builder.Services.AddBlazoredLocalStorage();
builder.Services.Replace(ServiceDescriptor.Scoped<IJsonSerializer, MySerializer>());

You can find an example of this in the Blazor Server sample project. The standard serializer has been replaced with a new serializer which uses NewtonsoftJson.

Testing with bUnit

The Blazored.LocalStorage.TestExtensions package provides test extensions for use with the bUnit testing library. Using these test extensions will provide an in memory implementation which mimics local storage allowing more realistic testing of your components.

Installing

To install the package add the following line to you csproj file replacing x.x.x with the latest version number (found at the top of this file):

<PackageReference Include="Blazored.LocalStorage.TestExtensions" Version="x.x.x" />

You can also install via the .NET CLI with the following command:

dotnet add package Blazored.LocalStorage.TestExtensions

If you're using Visual Studio you can also install via the built in NuGet package manager.

Usage example

Below is an example test which uses these extensions. You can find an example project which shows this code in action in the samples folder.

public class IndexPageTests : TestContext
{
    [Fact]
    public async Task SavesNameToLocalStorage()
    {
        // Arrange
        const string inputName = "John Smith";
        var localStorage = this.AddBlazoredLocalStorage();
        var cut = RenderComponent<BlazorWebAssembly.Pages.Index>();

        // Act
        cut.Find("#Name").Change(inputName);
        cut.Find("#NameButton").Click();
            
        // Assert
        var name = await localStorage.GetItemAsync<string>("name");
            
        Assert.Equal(inputName, name);
    }
}
Product Compatible and additional computed target framework versions.
.NET net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 is compatible.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 is compatible.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (128)

Showing the top 5 NuGet packages that depend on Blazored.LocalStorage:

Package Downloads
Blazored.LocalStorage.TestExtensions

A testing library to provide helper extensions for Blazored.LocalStorage

Blauhaus.MVVM.Blazor

Package Description

RapidCMS.UI

RapidCMS is a Blazor framework which allows you to build a responsive and flexible CMS purely from code.

Arc4u.Standard.OAuth2.Blazor

Package Description

KarcagS.Blazor.Common

Package Description

GitHub repositories (41)

Showing the top 5 popular GitHub repositories that depend on Blazored.LocalStorage:

Repository Stars
dotnet-architecture/eShopOnWeb
Sample ASP.NET Core 8.0 reference application, powered by Microsoft, demonstrating a layered application architecture with monolithic deployment model. Download the eBook PDF from docs folder.
MudBlazor/MudBlazor
Blazor Component Library based on Material design with an emphasis on ease of use. Mainly written in C# with Javascript kept to a bare minimum it empowers .NET developers to easily debug it if needed.
fullstackhero/blazor-starter-kit
Clean Architecture Template for Blazor WebAssembly Built with MudBlazor Components.
openbullet/OpenBullet2
OpenBullet reinvented
Webreaper/Damselfly
Damselfly is a server-based Photograph Management app. The goal of Damselfly is to index an extremely large collection of images, and allow easy search and retrieval of those images, using metadata such as the IPTC keyword tags, as well as the folder and file names. Damselfly includes support for object/face detection.
Version Downloads Last updated
4.5.0 769,578 2/10/2024
4.4.0 1,149,673 8/14/2023
4.3.0 2,020,367 11/9/2022
4.3.0-preview.1 129,032 3/28/2022
4.2.0 2,071,133 2/4/2022
4.1.5 892,735 8/21/2021
4.1.4 1,816 8/21/2021
4.1.2 237,016 6/13/2021
4.1.1 82,899 5/15/2021
4.0.0 27,543 5/8/2021
3.0.0 816,733 7/23/2020
2.2.0 8,023 7/23/2020
2.1.6 126,724 5/21/2020
2.1.5 67,879 3/31/2020
2.1.4 1,982 3/30/2020
2.1.3 4,211 3/27/2020
2.1.1 131,660 9/25/2019
2.1.0 2,838 9/19/2019
2.0.14 587 9/17/2019
2.0.13 1,071 9/5/2019
2.0.12 2,468 8/19/2019
2.0.11 877 8/14/2019
2.0.10 395 8/14/2019
2.0.9 373 8/14/2019
2.0.8 386 8/13/2019
2.0.7 1,000 7/27/2019
2.0.6 394 7/25/2019
2.0.5 392 7/25/2019
2.0.3 363 7/25/2019
2.0.2 1,180 6/13/2019
2.0.1 2,042 5/31/2019
2.0.0 3,174 4/19/2019
1.2.1 2,245 3/15/2019
1.2.0 1,876 3/13/2019
1.1.0 1,902 3/9/2019
1.0.4 1,770 3/9/2019
1.0.3 1,846 3/4/2019
1.0.2 1,786 3/2/2019
1.0.1 2,070 2/9/2019
1.0.0 2,081 1/30/2019