Your next page is taking shape...

Opening Your Next Page…

Loading the guide and preparing its examples for you to explore. The page will appear here automatically when it’s ready, so you can keep this view open without refreshing.

Made for Preact. Built to be yours.

kamod-signals · Persisted State · Familiar .value API

Persisted Preact Signals for Every Storage Driver

Reactive state with durable storage — localStorage, sessionStorage, IndexedDB, cookies, and memory — while keeping the familiar @preact/signals .value API.

Decide Which Values Should Survive a Reload before choosing a storage driver. Use a stable key, define a useful initial value, and keep the lifetime of the signal aligned with the screen, session or application that owns it. Pair it with the Component Library when building your interface. Continue with the Full Documentation for the complete package reference.


What the Package Brings

Use persistence for values that should outlive their current render. Decide what the preference belongs to, how long it should survive and how a user can return to the default.

Choose the Right Approach

A Preference Across Visits

Choose local storage for small, non-sensitive browser preferences.

A saved browser value is neither account synchronization nor authoritative server data.

A Shorter-Lived Browser Value

Choose session storage when the lifetime should follow that browser session.

Document which values survive refreshes and which should disappear on sign-out.

Server-Aware Persistence

Review the cookie driver and createCookieContext at the request boundary.

Cookie scope, response headers and request isolation belong to the server integration.

Persistence Built in

persistedSignal and usePersistedSignal sync reactive values to the driver you choose.

Give each preference a stable storage key and a useful initial value. Treat future changes to the stored shape as a migration decision, rather than assuming every returning visitor has fresh data.

Framework Friendly

Works beside Preact components and plain modules — share state across controllers without prop drilling.

Share a signal only when its consumers should share the same value. Keep temporary screen state local, and avoid copying persisted values into a second independently writable store.

SSR-Aware Cookies

createCookieContext and serializeCookie helpers keep cookie-backed signals usable on the server.

Keep request-specific cookie handling at the server boundary. Verify that the server and client agree on the initial value, and check what happens when there is no saved preference.

Installation

Add persistence to your signals setup. Install @kamod-ch/signals alongside @preact/signals and Preact, checking that the versions satisfy the package’s peer requirements. In an existing application, use the same signal runtime already used by your components.

Decide where the value will live. The Usage Example starts with a local browser preference. Before choosing a different storage driver, read Account for the Environment and the Driver Reference; browser storage and request-scoped cookies need different setup decisions.

Install PackagesTerminal
pnpm add @kamod-ch/signals @preact/signals preact

Check Your Environment

Use your existing package manager and keep the peer dependencies aligned with your application. Compare package.json and your lockfile with the documentation for the version you install; add the package once at the workspace boundary that uses it.

Keep the First Change Small. Start with the usage example, run your project’s typecheck and build, then connect it to a real screen. The Package Overview helps you decide how companion libraries fit together.

Usage

Give the preference a name, a default and an owner. Create a persistedSignal with a specific storage key and driver, then read or write its .value. A shared instance lets several consumers observe the same preference; use usePersistedSignal when the instance should follow a component’s lifetime.

Check the saved value, not just the current screen. Start with a harmless preference, change it, reload and restore its default. The Component Preference Example shows this flow with a versioned key. Review Ownership and Lifetime before moving the signal into a shared module, especially when your application renders on the server.

src/example.tsx6 lines
import { persistedSignal } from "@kamod-ch/signals";

export const theme = persistedSignal("theme", "dark", { storage: "local" });

// later
theme.value = "light";

Read the Example

Follow the value from its definition to the interface. Each part below explains a decision to keep when adapting the example.

Give the Saved Value a Clear Owner

The key identifies browser storage, while the variable identifies the live signal. Decide whether it is a device preference or belongs to a signed-in account before sharing the key across screens or sessions.

Usage PatternTypeScript
const theme = persistedSignal("theme", "dark", { storage: "local" });
Read and Write through One Signal

Consumers should observe the same instance. Copying the value into unrelated local state creates a second owner that can become stale. Keep derived presentation derived, rather than synchronizing two writable values with effects.

Usage PatternTypeScript
theme.value = "light";
Provide an Explicit Reset

Reset restores the initial value; clearing a stored entry is a separate operation. Use an explicit user action for preference resets, and verify the behavior after reload rather than only checking the currently rendered label.

Usage PatternTypeScript
theme.reset();

Keep a Preference Local to a Component

A custom hook can keep the persistent preference close to the settings control. The versioned key below leaves room for a future storage-shape change. This example is intentionally a harmless preference, not authentication or private user data.

src/components/DensityPreference.tsx14 lines
import { usePersistedSignal } from "@kamod-ch/signals";
import { Button } from "@kamod-ch/ui";

export function DensityPreference() {
  const compact = usePersistedSignal("ui:compact:v1", false, { storage: "local" });
  return (
    <div class="flex flex-wrap gap-2">
      <Button aria-pressed={compact.value} onClick={() => { compact.value = !compact.value; }}>
        Compact spacing
      </Button>
      <Button variant="ghost" onClick={() => compact.reset()}>Restore default</Button>
    </div>
  );
}

Try the Boundaries. Toggle, reload and restore the default. Then test without a stored value and with browser storage restricted. For SSR, ensure the first client render agrees with the server; browser-only preferences cannot automatically be known by the server.

Integrate with Your Application

Persist Preferences Deliberately. A color scheme or density setting has a different lifetime from a draft or an account-specific value. Name keys clearly, decide when they should be reset and avoid retaining temporary UI state without a reason.

The module-level usage example demonstrates a shared signal. In a server-rendered application, do not share user-specific mutable state across requests. Follow the package’s SSR and cookie guidance when a preference must be available before hydration.

Keep reads and writes through the signal’s .value interface and review how your chosen driver handles unavailable storage. Plan for old stored values when you change a preference’s shape or allowed options.

Choose the Owner and Lifetime

Name keys by purpose and treat a stored shape as a small data contract. Give defaults the same care as saved values. Decide whether clearing a preference means removing storage, resetting the live value, or both. For account-specific settings, define sign-out behavior and avoid silently applying one user's saved value to the next user on the device.

Account for the Environment

Storage availability, hydration and cross-tab updates are separate concerns. Test the chosen driver in the actual environment instead of assuming all storage behaves like synchronous local storage. If a preference changes layout, make the initial server and client output compatible and avoid a second competing copy of the value in component state.

Connect the Pieces. Reducer State — Use explicit events and transitions when a workflow needs more structure than a persisted preference.

Integration goal
What a good integration looks like

Persistence needs a reset policy as well as a save path. Decide which values remain after sign-out, which expire with the session and which should never be stored at all.

When Something Behaves Differently

Start with the smallest failing interaction. Compare a fresh page with the same page after a change or reload, and keep the package version in your reproduction.

A value changes back after refresh
Check the storage driver, key and write path. Make sure the code updates .value on the intended persisted signal rather than a separate temporary variable.
A returning visitor sees invalid data
Inspect the saved shape from older releases. Validate or migrate before using it, and provide a reset path when the value cannot be recovered.
Two controls disagree
Confirm that they are meant to share a source and review the driver's synchronization behavior. Matching variable names do not guarantee matching signal instances or storage keys.

If the behavior still differs from the documented API, Check Existing Issues before opening a report. Include the expected result, actual result, package version and a small reproduction without private application data.

API Reference

This page is a Kamod UI overview. Full API docs, driver tables, and SSR cookie examples live on the dedicated kamod-signals docs.

Use this page to understand the integration, then consult the Full API Reference on Live Docs for exact signatures and supported options. Compare those details with the version in your lockfile before adapting an example.

Explore Drivers, API, and Examples

Open the kamod-signals docs for getting started, storage showcases, and SSR cookie guides.

  • Before Choosing an API: read its input types, return values and default behavior.
  • Before Shipping: review lifecycle or server-rendering notes for the features you use.
  • When Behavior Differs: reduce the case to a small example and include your package version in the report.
Continue with the dedicated package documentation.Open Live Docs

Accessibility Notes

When signals drive UI chrome (theme, sidebar, locale), reflect state in accessible controls and keep preference changes predictable for keyboard and assistive tech users.

Before You Ship

  • Try a fresh visit, a saved preference and an explicit reset.
  • Test your chosen driver with unavailable storage and unexpected stored values.
  • Verify that account or request-specific data cannot leak through shared module state.

Review the result with Real Content and Keyboard Input. Keep visible labels, loading and error feedback, and focus behavior in sync with the state your application exposes.

Take the Guide with You

Keep the Examples, Integration Decisions and Troubleshooting Notes together in your project, or share them with a coding assistant. This reference works with any assistant; no model-specific setup is needed. Check the installed version and your project’s conventions before applying a suggestion.

Keep It HandyReady for your project
DownloadMarkdown
signals-package-reference.md165 lines
# Signals — integration reference

Reactive state with durable storage — localStorage, sessionStorage, IndexedDB, cookies, and memory — while keeping the familiar @preact/signals .value API.

Package: @kamod-ch/signals

## Choose an approach

Use persistence for values that should outlive their current render. Decide what the preference belongs to, how long it should survive and how a user can return to the default.

### A preference across visits

Choose local storage for small, non-sensitive browser preferences.

A saved browser value is neither account synchronization nor authoritative server data.

### A shorter-lived browser value

Choose session storage when the lifetime should follow that browser session.

Document which values survive refreshes and which should disappear on sign-out.

### Server-aware persistence

Review the cookie driver and createCookieContext at the request boundary.

Cookie scope, response headers and request isolation belong to the server integration.

## Installation

**Add persistence to your signals setup.** Install `@kamod-ch/signals` alongside `@preact/signals` and Preact, checking that the versions satisfy the package’s peer requirements. In an existing application, use the same signal runtime already used by your components.

**Decide where the value will live.** The [Usage Example](https://ui.kamod.ch/docs/signals-package/installation#usage) starts with a local browser preference. Before choosing a different storage driver, read [Account for the Environment](https://ui.kamod.ch/docs/signals-package/installation#environment-boundaries) and the [Driver Reference](https://ui.kamod.ch/docs/signals-package/installation#api-reference); browser storage and request-scoped cookies need different setup decisions.

```bash
pnpm add @kamod-ch/signals @preact/signals preact
```

## Starting example

**Give the preference a name, a default and an owner.** Create a `persistedSignal` with a specific storage key and driver, then read or write its `.value`. A shared instance lets several consumers observe the same preference; use `usePersistedSignal` when the instance should follow a component’s lifetime.

**Check the saved value, not just the current screen.** Start with a harmless preference, change it, reload and restore its default. The [Component Preference Example](https://ui.kamod.ch/docs/signals-package/installation#put-it-to-work) shows this flow with a versioned key. Review [Ownership and Lifetime](https://ui.kamod.ch/docs/signals-package/installation#state-and-lifetime) before moving the signal into a shared module, especially when your application renders on the server.

```tsx
import { persistedSignal } from "@kamod-ch/signals";

export const theme = persistedSignal("theme", "dark", { storage: "local" });

// later
theme.value = "light";
```

### Give the Saved Value a Clear Owner

The key identifies browser storage, while the variable identifies the live signal. Decide whether it is a device preference or belongs to a signed-in account before sharing the key across screens or sessions.

```tsx
const theme = persistedSignal("theme", "dark", { storage: "local" });
```

### Read and Write through One Signal

Consumers should observe the same instance. Copying the value into unrelated local state creates a second owner that can become stale. Keep derived presentation derived, rather than synchronizing two writable values with effects.

```tsx
theme.value = "light";
```

### Provide an Explicit Reset

Reset restores the initial value; clearing a stored entry is a separate operation. Use an explicit user action for preference resets, and verify the behavior after reload rather than only checking the currently rendered label.

```tsx
theme.reset();
```

## Keep a Preference Local to a Component

A custom hook can keep the persistent preference close to the settings control. The versioned key below leaves room for a future storage-shape change. This example is intentionally a harmless preference, not authentication or private user data.

File: src/components/DensityPreference.tsx

```tsx
import { usePersistedSignal } from "@kamod-ch/signals";
import { Button } from "@kamod-ch/ui";

export function DensityPreference() {
  const compact = usePersistedSignal("ui:compact:v1", false, { storage: "local" });
  return (
    <div class="flex flex-wrap gap-2">
      <Button aria-pressed={compact.value} onClick={() => { compact.value = !compact.value; }}>
        Compact spacing
      </Button>
      <Button variant="ghost" onClick={() => compact.reset()}>Restore default</Button>
    </div>
  );
}
```

Toggle, reload and restore the default. Then test without a stored value and with browser storage restricted. For SSR, ensure the first client render agrees with the server; browser-only preferences cannot automatically be known by the server.

## Ownership and environment

Name keys by purpose and treat a stored shape as a small data contract. Give defaults the same care as saved values. Decide whether clearing a preference means removing storage, resetting the live value, or both. For account-specific settings, define sign-out behavior and avoid silently applying one user's saved value to the next user on the device.

Storage availability, hydration and cross-tab updates are separate concerns. Test the chosen driver in the actual environment instead of assuming all storage behaves like synchronous local storage. If a preference changes layout, make the initial server and client output compatible and avoid a second competing copy of the value in component state.

Persistence needs a reset policy as well as a save path. Decide which values remain after sign-out, which expire with the session and which should never be stored at all.

## Troubleshooting

### A value changes back after refresh

Check the storage driver, key and write path. Make sure the code updates .value on the intended persisted signal rather than a separate temporary variable.

### A returning visitor sees invalid data

Inspect the saved shape from older releases. Validate or migrate before using it, and provide a reset path when the value cannot be recovered.

### Two controls disagree

Confirm that they are meant to share a source and review the driver's synchronization behavior. Matching variable names do not guarantee matching signal instances or storage keys.

## Resources

- [Dedicated documentation](https://kamod-ch.github.io/kamod-signals/) — Exact signatures, supported options and deeper examples.

- [Source & release history](https://github.com/kamod-ch/kamod-signals) — Implementation, release notes and the project’s issue tracker.

- [Published package](https://www.npmjs.com/package/@kamod-ch/signals) — Compare the version and peer requirements with your lockfile.

When copying or distributing source, retain the applicable license and attribution notices from the version you use.

## Companion packages

Persistence gives a value a longer life. Keep the surrounding behavior, domain events and display text with the packages that own those responsibilities.

### Hooks — Keep the temporary bits temporary

[`@kamod-ch/hooks`](https://ui.kamod.ch/docs/hooks-package/installation)

Save the user’s preference, but keep an open menu or unfinished hover interaction local. Hooks help a component manage its own behavior while the persisted signal remains the single source for the durable value.

### State — Separate remembering from deciding

[`@kamod-ch/state`](https://ui.kamod.ch/docs/state-package/installation)

Use a reducer when a feature needs explicit domain transitions. If selected preferences also need persistence, define the read/write boundary deliberately; the State signals bridge does not automatically persist a store through this package.

### i18n — Restore a preference, then resolve a locale

[`@kamod-ch/i18n`](https://ui.kamod.ch/docs/i18n-package/installation)

A saved language identifier can inform the translation setup after validation. Specify precedence between storage, routing and server data, and resolve the initial locale consistently so restoring a preference does not flash the wrong language.

## Make a preference earn its place.

Connect one harmless display setting to a Switch, reload the page and offer a clear reset. Test an older stored value too: a preference is only convenient when returning visitors can recover from changes to its shape.

[Connect a preference control](https://ui.kamod.ch/docs/switch/installation)

Check fresh storage, unavailable storage, sign-out behavior and restoring the default.

[All packages](https://ui.kamod.ch/docs/packages) · [The wider ecosystem](https://ui.kamod.ch/docs/ecosystem)
Display changes only the view. Copy and download include the complete Markdown reference.

Sources & Attribution

This integration guide accompanies @kamod-ch/signals, maintained in the Kamod ecosystem. The Dedicated Documentation is the reference for package APIs; examples here show how those APIs fit into a Kamod UI application.

Make a Preference Earn Its Place.

Connect one harmless display setting to a Switch, reload the page and offer a clear reset. Test an older stored value too: a preference is only convenient when returning visitors can recover from changes to its shape.

Check fresh storage, unavailable storage, sign-out behavior and restoring the default.

Take the Next Useful Step

You have the pieces. Put them into one real interaction, keep its state in one place, and check the result with the content your application will actually show.

Connect the Foundation

Return to Choose Your Companion Packages to connect this reference to a working screen. Keep global CSS in one entrypoint and import only the components that screen needs.

Build the Surrounding Screen

Find a neighboring interaction in the Component Library, or start with a complete Block. Replace sample content and destinations before refining the layout; a local class change can stay with the composition.

Make the Result Hold Up

Use shared theme roles for changes that belong everywhere. Then review the whole journey: keyboard focus, long labels, narrow screens and a clear way to recover when something fails.

Keep a link to the source and note your intentional changes. Your next edit should begin with a clear decision, not another search.