Local Storage

The LocalStorage service wraps the browser’s localStorage so it can be used safely during server rendering. Values set on the server are carried to the browser through TransferState.

Overview

Applications often keep preferences like themes, layout states, and onboarding steps in localStorage, which does not exist during server rendering. The service keeps values in memory on the server and uses the browser’s storage in the browser.

Familiar Methods

Has the same six members as the native Storage: length, key(), getItem(), setItem(), removeItem() and clear(). Keys and values are strings. It is a service, not a Storage instance, so values are read and written through these methods only, not as properties.

Server Rendering

Keeps values in a Map on the server and transfers them to the browser’s storage.

Unavailable Storage

Stays inert in the browser when no storage can be reached.

Provider Setup

Add provideLocalStorage to the providers array of your application configuration. It requires provideWindow:

import { provideLocalStorage } from '@/app/core/local-storage';
import { provideWindow } from '@/app/core/window';

export const appConfig: ApplicationConfig = {
  providers: [
    provideLocalStorage(),
    provideWindow(),
    // ...other providers
  ],
};

Usage

private localStorage = inject(LocalStorage);

saveView(view: string) {
  this.localStorage.setItem('view', view);
}

readView() {
  return this.localStorage.getItem('view') ?? 'grid';
}

resetView() {
  this.localStorage.removeItem('view');
}

Values are stored as strings. To store objects or arrays, convert them with JSON.stringify and read them back with JSON.parse:

saveFilters(filters: string[]) {
  this.localStorage.setItem('filters', JSON.stringify(filters));
}

readFilters(): string[] {
  return JSON.parse(this.localStorage.getItem('filters') ?? '[]');
}

Server Rendering

On the server, values live in a Map that starts empty on every request. The server cannot see the browser’s storage, so getItem returns null there unless the key was set during the same render.

Values set during server rendering travel to the browser through TransferState and are written into its localStorage when the service is created, replacing any existing value for the same keys.

Only write on the server when that is what you want. For user preferences, write in the browser only. Theming does the same and skips its storage writes on the server:

private localStorage = inject(LocalStorage);
private isServer = isPlatformServer(inject(PLATFORM_ID));

saveView(view: string) {
  if (this.isServer) {
    return;
  }

  this.localStorage.setItem('view', view);
}

Unavailable Storage

In the browser, when localStorage is missing or access to it is denied, for example in sandboxed iframes or with blocked site data, the service stays inert: writes are dropped, reads return null and length is 0. Nothing is kept in memory instead. When storage is available, setItem behaves like the native method, including the error it throws when the storage quota is exceeded.