Forem: Gaurav Kumar Singh

Internals of useLocalStorageState Hook

Gaurav Kumar Singh — Sun, 24 May 2026 14:59:48 +0000

How My React useLocalStorageState/localStorage Hook Works Internally

I built @gks101/localyx to make localStorage easier to use in React.

The main hook is called useLocalStorageState.

It lets you write code that feels like useState, but the value is also saved in the browser.

Package:

npm install @gks101/localyx

GitHub repo:

https://github.com/gaurav101/localyx

Working demo:

https://localyx.vercel.app/

In this article, I will explain how the hook works internally in simple steps.

This article is for React beginners who already know basic useState and useEffect.

The Basic Idea

Normal React state looks like this:

const [theme, setTheme] = useState("light");

But this value is lost when the page refreshes.

localStorage can save data after refresh, but using it directly can become messy.

So the hook gives us this:

const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

It returns:

theme: the current value
setTheme: a function to update the value
clearTheme: a function to remove the value

Internally, the hook connects React state with localStorage.

The Stored Data Shape

The hook does not save only the value.

It saves an object like this:

{
  v: value,
  t: timestamp
}

In the source code, this is called StorageEntry.

interface StorageEntry<T> {
  v: T;
  t?: number;
}

Here:

v means the real value
t means the time when the value was saved

The timestamp is optional.

It is only needed when TTL expiry is used.

TTL means "Time To Live". It tells the hook when a value should expire.

The Options Object

The hook accepts an optional third argument.

useLocalStorageState("theme", "light", options);

The options include:

{
  ttl?: number;
  ttlStrategy?: "absolute" | "sliding";
  namespace?: string;
  onExpire?: (ctx) => void;
  encrypt?: ((raw: string) => string) | null;
  decrypt?: ((raw: string) => string) | null;
  serializer?: {
    stringify: (value) => string;
    parse: (value) => value;
  };
}

These options let the hook support expiry, namespaces, custom encoding, and custom parsing.

Browser Safety

localStorage only exists in the browser.

It does not exist during server-side rendering.

That is why the hook has a helper called isBrowser.

const isBrowser = (): boolean =>
  typeof window !== "undefined" && typeof localStorage !== "undefined";

This protects the code from crashing in tools like Next.js.

Before reading or writing localStorage, the hook checks if it is running in the browser.

Safe Read, Write, and Delete Helpers

The hook uses small wrapper functions around localStorage.

function lsRead(key: string): string | null {
  try {
    return isBrowser() ? localStorage.getItem(key) : null;
  } catch {
    return null;
  }
}

There are also helpers for writing and deleting.

Why use wrappers?

Because localStorage can fail in some cases.

For example:

browser storage is disabled
storage is full
the app is running outside the browser
the saved data is not valid

The wrapper functions make the hook safer.

Instead of crashing the app, the hook falls back to the initial value.

Creating the Final Storage Key

The hook supports namespaces.

This means the user can write:

useLocalStorageState("profile", null, {
  namespace: "my-app",
});

Internally, the key becomes:

my-app:profile

The helper looks like this:

function resolveStorageKey(key: string, namespace?: string): string {
  return namespace ? `${namespace}:${key}` : key;
}

This is useful when a project has many localStorage values.

It helps avoid key conflicts.

Encoding and Decoding the Value

Before the hook saves data, it turns the data into a string.

By default, it uses JSON:

JSON.stringify(entry)

Then it can encode the string.

By default, the hook uses Base64 encoding.

Base64 is not real encryption. It only makes the saved value less readable.

If someone needs real security, they should pass custom encrypt and decrypt functions.

The hook also allows plain JSON:

useLocalStorageState("theme", "light", {
  encrypt: null,
  decrypt: null,
});

When encrypt and decrypt are null, the hook skips encoding and decoding.

Reading the Value on First Render

This is one of the most important parts.

When the component first renders, the hook tries to read from localStorage.

const [state, setInternalState] = useState<T>(() => readStorage());

Notice that readStorage is passed as a function.

This is called lazy initialization.

It means React only calls readStorage during the first render.

This is better than reading from localStorage on every render.

Inside readStorage, the hook does these steps:

Read the raw value from localStorage.
If there is no value, return the initial value.
Decode the value if needed.
Parse the JSON.
If parsing fails, delete the broken value.
If the value is expired, delete it.
If the value is valid, return entry.v.

So the component receives the real saved value.

Handling Broken Data

Sometimes localStorage may contain broken data.

For example, maybe the value was edited manually in browser devtools.

The hook uses parseStorageEntry for this.

function parseStorageEntry(raw, decode, parse) {
  try {
    const decoded = decode ? decode(raw) : raw;
    return parse(decoded);
  } catch {
    return null;
  }
}

If parsing fails, it returns null.

Then the hook removes the invalid value and returns the initial value.

This keeps the app stable.

Updating the Value

The hook gives us a setter function.

setTheme("dark");

Internally, the setter does more work than normal useState.

It:

Gets the next value.
Wraps it in a storage entry.
Adds a timestamp if TTL is enabled.
Converts it to a string.
Encodes it if needed.
Saves it to localStorage.
Updates React state.
Sends a sync event.

The hook also supports updater functions:

setTheme((oldTheme) => oldTheme === "light" ? "dark" : "light");

This works like normal React state.

That makes the hook easier to learn because it follows a familiar pattern.

Removing the Value

The hook returns a third function called removeValue.

Example:

const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

When we call:

clearTheme();

The hook:

Deletes the value from localStorage.
Sends a sync event.
Sets React state back to the initial value.

This is useful for reset buttons, logout buttons, and clearing old settings.

Same Tab Sync

This hook supports Same Tab Sync.

This means if two components on the same page use the same key, they can stay updated.

Example:

function Header() {
  const [theme] = useLocalStorageState("theme", "light");
  return <p>{theme}</p>;
}

function Settings() {
  const [theme, setTheme] = useLocalStorageState("theme", "light");
  return <button onClick={() => setTheme("dark")}>Dark</button>;
}

If Settings updates the theme, Header should also get the new value.

The browser storage event does not fire in the same tab that made the change.

So the hook creates its own custom event:

const LOCAL_SYNC_EVENT = "__localyx_sync__";

When the value changes, the hook dispatches this event.

Other hook instances in the same tab listen for it and update their state.

Cross Tab Sync

The hook also supports Cross Tab Sync.

This means if the app is open in two browser tabs, changes can move from one tab to another.

The browser already gives us a storage event for this.

The hook listens to it:

window.addEventListener("storage", onStorage);

When another tab changes the same localStorage key, this tab receives the new value.

Then the hook:

Checks if the key is the same.
Parses the new value.
Checks if it is expired.
Updates React state.

This makes the UI feel consistent across tabs.

TTL Expiry

TTL means a value should expire after some time.

Example:

const [token, setToken] = useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
});

This means the value expires after 10 minutes.

When TTL is enabled, the hook saves a timestamp:

{
  v: token,
  t: Date.now()
}

Later, it checks:

now >= savedTime + ttl

If this is true, the value has expired.

Then the hook deletes it and returns the initial value.

Absolute TTL

The default TTL strategy is absolute.

Example:

useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  ttlStrategy: "absolute",
});

If the value is saved at 10:00, it expires at 10:10.

It does not matter if the user keeps reading the value.

This is good for strict expiry.

Good examples:

auth-like temporary values
one-time data
fixed cache expiry

Sliding TTL

The second TTL strategy is sliding.

Example:

useLocalStorageState("search_cache", "", {
  ttl: 5 * 60 * 1000,
  ttlStrategy: "sliding",
});

Sliding TTL refreshes the timestamp when the value is used.

In the code, this happens in touchSlidingTtl.

If the value is still active, the hook updates t to the current time.

This keeps active data alive for longer.

Good examples:

active UI cache
recent filters
data that should expire only after inactivity

Auto Cleanup with setTimeout

The hook does not only check expiry when reading.

It also sets a timer.

window.setTimeout(...)

The timer waits until the saved value should expire.

When the timer runs, the hook reads the latest value again.

This is important because the value may have changed before the timer ended.

Then it checks if the latest value is expired.

If yes, it removes it and updates state.

This keeps the current tab clean without waiting for a page refresh.

The onExpire Callback

The hook lets users pass onExpire.

useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  onExpire: ({ key, value }) => {
    console.log("Expired:", key, value);
  },
});

When the value expires, the hook calls this function.

This can be used to:

show a message
log out a user
clear other related values
track expiry behavior

The Internal expiryTick State

There is a small internal state called expiryTick.

const [expiryTick, setExpiryTick] = useState(0);

This value is not shown to the user.

It only helps the hook re-run the expiry timer effect.

When a TTL value changes or is removed, the hook updates expiryTick.

That tells React:

Please run the expiry effect again.

This keeps the timer in sync with the latest saved value.

Why useCallback Is Used

The hook uses useCallback for internal functions like:

readStorage
setState
removeValue
expireEntry
touchSlidingTtl

useCallback helps keep function references stable between renders.

This is useful because some of these functions are used inside useEffect.

It helps React know when an effect should run again.

For beginners, the simple explanation is:

useCallback helps the hook avoid recreating important functions unless their inputs change.

The getRemainingTtl Helper

The package also exports getRemainingTtl.

Example:

import { getRemainingTtl } from "@gks101/localyx";

const remainingMs = getRemainingTtl("token", 10 * 60 * 1000);

Internally, it:

Builds the final storage key.
Reads the saved value.
Decodes and parses it.
Checks the saved timestamp.
Returns the remaining time.

It can return:

a number when time is left
0 when the value has expired
null when there is no valid TTL data

This is useful when you want to show a timer or debug expiry behavior.

Full Flow in Simple Words

Here is the full flow of the hook:

Build the final key.
Choose JSON or custom serializer.
Choose Base64 or custom encode/decode.
Read old data from localStorage.
Validate and parse the old data.
Check if the old data is expired.
Put the value into React state.
When the setter is called, update state and localStorage.
Notify other hook instances in the same tab.
Listen for updates from other browser tabs.
If TTL is enabled, schedule cleanup.
If the value expires, remove it and reset state.

Small Example of the Final API

import { useLocalStorageState } from "@gks101/localyx";

function App() {
  const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light", {
    namespace: "demo-app",
    ttl: 24 * 60 * 60 * 1000,
  });

  return (
    <div>
      <p>Theme: {theme}</p>

      <button onClick={() => setTheme("dark")}>
        Dark
      </button>

      <button onClick={() => setTheme("light")}>
        Light
      </button>

      <button onClick={clearTheme}>
        Reset
      </button>
    </div>
  );
}

Why This Hook Is Useful

This hook is useful because it handles many small details in one place.

Without a hook, every component may need to repeat the same logic.

With this hook, the component only focuses on the UI.

The hook handles:

saving
loading
parsing
deleting
expiry
Same Tab Sync
Cross Tab Sync
custom serialization
custom encoding

Final Thoughts

The main goal of useLocalStorageState is to make browser storage feel simple in React.

It behaves like useState, but it also remembers the value after refresh.

It also adds useful features like TTL expiry, same tab sync, cross tab sync, namespaces, and custom serialization.

If you are a beginner, you can first use the basic API.

Then, when your app needs more control, you can start using the options one by one.

Install:

npm install @gks101/localyx

GitHub:

https://github.com/gaurav101/localyx

Demo:

https://localyx.vercel.app/

A Simple React Hook for localStorage State, Expiry, and Sync

Gaurav Kumar Singh — Thu, 21 May 2026 13:21:38 +0000

Hi everyone! I'm Gaurav, and I am incredibly excited to share my very first article with the DEV Community! As a developer, I love building open-source tools that solve everyday workflow headaches and make life a bit easier for the community. I wrote this article to share what I learned while building my latest package, and I hope it helps you level up your React storage management.

When we build React apps, we often need to save small values in the browser.

For example:

selected theme
user settings
form draft
search filters
temporary session value
cached API response

The browser already gives us localStorage, but using it directly in React can become repetitive.

We usually need to:

read the value from localStorage
parse the saved JSON
handle missing or broken data
update React state
write the new value back to localStorage
remove the value when needed
sync the value between tabs
expire old values after some time

This is why I built @gks101/localyx.

It is a small React hook that helps you use localStorage like normal React state.

Main Features

simple useState-like API
saves state in localStorage
Same Tab and Cross Tab Sync
TTL expiry support
absolute and sliding expiry strategies
namespace support
custom serializer support
custom encrypt and decrypt support
helper function to check remaining TTL

Working demo:

https://localyx.vercel.app/

GitHub repo:

https://github.com/gaurav101/localyx

NPM package:

npm install @gks101/localyx

What Problem Does It Solve?

React state is simple:

const [value, setValue] = useState("hello");

But normal React state is lost when the page is refreshed.

localStorage can keep data after refresh, but it does not work like React state by default.

So I wanted a hook that feels like useState, but also saves the value in localStorage.

That is the main idea of useLocalStorageState.

Basic Usage

First install the package:

npm install @gks101/localyx

Then import the hook:

import { useLocalStorageState } from "@gks101/localyx";

Now use it inside a component:

import { useLocalStorageState } from "@gks101/localyx";

function ThemeToggle() {
  const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

  return (
    <div>
      <p>Current theme: {theme}</p>

      <button onClick={() => setTheme(theme === "light" ? "dark" : "light")}>
        Toggle Theme
      </button>

      <button onClick={clearTheme}>
        Reset Theme
      </button>
    </div>
  );
}

This looks very close to useState.

The hook returns three values:

const [state, setState, removeValue] = useLocalStorageState(key, initialValue);

Step 1: The Key

The first value is the localStorage key.

useLocalStorageState("theme", "light");

Here, "theme" is the key.

The hook will save the value in localStorage using this key.

Step 2: The Initial Value

The second value is the default value.

useLocalStorageState("theme", "light");

Here, "light" is the initial value.

The hook will use this value when:

nothing is saved in localStorage
the saved data is invalid
the saved data has expired
you remove the value

Step 3: Reading the State

The first returned value is the current state.

const [theme] = useLocalStorageState("theme", "light");

You can show it in your UI:

<p>Current theme: {theme}</p>

When the page refreshes, the hook reads the saved value from localStorage.

Step 4: Updating the State

The second returned value is the setter function.

const [theme, setTheme] = useLocalStorageState("theme", "light");

You can use it like setState:

setTheme("dark");

You can also use the previous value:

setTheme((oldTheme) => oldTheme === "light" ? "dark" : "light");

When you call setTheme, the hook updates React state and also saves the new value in localStorage.

Step 5: Removing the Value

The third returned value removes the saved data.

const [theme, setTheme, clearTheme] = useLocalStorageState("theme", "light");

Use it like this:

clearTheme();

This removes the value from localStorage and sets the state back to the initial value.

TTL: Expire Data After Some Time

Sometimes we do not want to keep data forever.

For example, a session value or cache value should expire after some time.

TTL means "Time To Live".

You can pass ttl in milliseconds.

import { useLocalStorageState } from "@gks101/localyx";

function SessionExample() {
  const [session, setSession, clearSession] = useLocalStorageState<string | null>(
    "session",
    null,
    {
      ttl: 30 * 60 * 1000,
    }
  );

  return (
    <div>
      <p>{session ?? "No active session"}</p>

      <button onClick={() => setSession("my-session-token")}>
        Login
      </button>

      <button onClick={clearSession}>
        Logout
      </button>
    </div>
  );
}

In this example, the session expires after 30 minutes.

After expiry, the hook removes the old value and returns the initial value.

Absolute TTL

By default, TTL uses the absolute strategy.

This means the timer starts when the value is saved.

Example:

const [token, setToken] = useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  ttlStrategy: "absolute",
});

If the value is saved at 10:00, it will expire at 10:10.

Even if the user keeps using the app, the value still expires at that time.

This is useful for things like:

login session expiry
one-time temporary values
short-lived cache

Sliding TTL

The hook also supports sliding TTL.

const [searchCache, setSearchCache] = useLocalStorageState("search_cache", "", {
  ttl: 5 * 60 * 1000,
  ttlStrategy: "sliding",
});

Sliding TTL refreshes the timer when the value is read or synced.

This means active data can stay alive while the user is still using it.

This is useful for:

active session-like data
recently used filters
temporary UI cache

Run Code When a Value Expires

You can pass onExpire.

This function runs when the hook finds that the value has expired.

const [token, setToken] = useLocalStorageState("token", null, {
  ttl: 10 * 60 * 1000,
  onExpire: ({ key, value }) => {
    console.log("Expired key:", key);
    console.log("Expired value:", value);
  },
});

This is useful when you want to:

show a message
logout the user
clear related data
send an analytics event

Namespaces

Sometimes many features use localStorage.

To avoid key conflicts, you can use a namespace.

const [profile, setProfile] = useLocalStorageState("profile", null, {
  namespace: "my-app",
});

This stores the value using this key:

my-app:profile

Namespaces are useful when:

you have many stored values
you are building a large app
you want to separate app versions
you want cleaner localStorage keys

Same Tab and Cross Tab Sync

If you open the same app in two browser tabs, the hook can keep values in sync.

For example:

Open the app in Tab 1.
Open the app in Tab 2.
Change the theme in Tab 1.
Tab 2 gets the new value too.

The hook also handles same-tab sync.

This is useful when two components use the same storage key on the same page.

Get Remaining TTL

The package also exports getRemainingTtl.

This helper tells you how much time is left before a saved value expires.

import { getRemainingTtl } from "@gks101/localyx";

const remainingMs = getRemainingTtl("session", 30 * 60 * 1000);

console.log(remainingMs);

It returns:

a number if time is remaining
0 if the value is already expired but not cleaned yet
null if the key does not exist or the value has no TTL data

You can also use it with a namespace:

const remainingMs = getRemainingTtl("session", 30 * 60 * 1000, {
  namespace: "my-app",
});

Custom Serialization

By default, the hook uses JSON.

For most React apps, that is enough.

But you can provide your own serializer if you need custom behavior.

const [value, setValue] = useLocalStorageState("custom", "hello", {
  serializer: {
    stringify: (value) => JSON.stringify(value),
    parse: (value) => JSON.parse(value),
  },
});

This is useful when you want more control over how data is saved and loaded.

Encoding and Encryption

By default, the hook stores data with Base64 encoding.

Base64 is only obfuscation. It is not real security.

If you need real security, pass your own encrypt and decrypt functions.

const encrypt = (raw: string) => {
  return btoa(raw);
};

const decrypt = (raw: string) => {
  return atob(raw);
};

const [secret, setSecret] = useLocalStorageState("secret", "hello", {
  encrypt,
  decrypt,
});

If you want to store plain JSON without Base64 encoding, pass null:

const [value, setValue] = useLocalStorageState("plain", "hello", {
  encrypt: null,
  decrypt: null,
});

Important note: do not store highly sensitive data in localStorage unless you fully understand the security risks.

SSR Safe

The hook has guards for browser-only APIs.

This means it can be used in apps that render on the server, like Next.js.

It will not directly access window or localStorage when they are not available.

Where Can You Use This Hook?

You can use this hook in many React projects.

Good use cases:

dark mode or theme setting
language preference
sidebar open or closed state
table filters
search filters
sort order
form draft
shopping cart for small projects
temporary session value
API cache with expiry
feature flag cache
onboarding step progress
recently viewed items

Avoid using it for:

passwords
private tokens without a security plan
very large data
data that must always be correct on the server

You Can Also Copy the Hook Into Your Project

You do not have to use the npm package if you do not want another dependency.

You can also copy the hook file from the GitHub repo and use it directly in your project.

Repo link:

https://github.com/gaurav101/localyx

This can be useful when:

you want full control over the code
you want to change the hook for your app
you are learning how the hook works
you want to avoid adding a package

Full API

Main hook:

useLocalStorageState<T>(key, initialValue, options?)

It returns:

[state, setState, removeValue]

Options:

{
  ttl?: number;
  ttlStrategy?: "absolute" | "sliding";
  namespace?: string;
  onExpire?: (ctx: { key: string; value: T }) => void;
  now?: () => number;
  encrypt?: ((raw: string) => string) | null;
  decrypt?: ((raw: string) => string) | null;
  serializer?: {
    stringify: (value: T) => string;
    parse: (value: string) => T;
  };
}

Helper:

getRemainingTtl(key, ttl, options?)

Final Thoughts

I built @gks101/localyx because I wanted a simple way to use localStorage in React without writing the same logic again and again.

It gives you a useState-like API, but also adds useful features like expiry, sync, namespaces, and custom serialization.

If you are a React beginner, you can start with the basic example first.

Later, when you need expiry or sync, the hook already supports it.

Package:

npm install @gks101/localyx

GitHub:

https://github.com/gaurav101/localyx

I would absolutely love to hear your thoughts, feedback, or any questions you have in the comments below—let's connect!

gaurav101 (Gaurav Kumar Singh) · GitHub

Full-stack developer passionate about building scalable applications and exploring new technologies. - gaurav101

github.com