09

Persist Handler

Automatic signal persistence with localStorage and sessionStorage

Basic Signal Persistence

Values automatically saved to localStorage and restored on page load:

Text Input Persistence

Current value:

Try typing, then refresh the page!

Counter with Reset Button

Counter persists across page reloads, but reset clears both display and storage:

Persistent Counter

Count:

Session Storage (Tab-Only)

This data is only saved for this browser tab and cleared when the tab closes:

Session-Only Data

Session value:

🔄 Refresh this tab: data persists

🆕 Open in new tab: data doesn't persist

Selective Signal Persistence

Choose which signals to persist and which to keep temporary:

Mixed Persistence

Persistent Score:
Temporary Lives:

Reload the page: score persists, lives reset to 3

Theme Toggle with Persistence

Toggle between light and dark themes - your preference is remembered:

Theme Preferences

Current theme:

Your theme choice persists across page reloads!

Features

Demonstrating different persistence patterns:

Disabled Persistence

Temp counter:

This counter will reset on every page reload (persistence disabled).

Custom Storage Key

App Version:
User Preference:

These values use a custom storage key: 'starhtml-persist-myapp'

Session-Only Specific Signal

Tab ID:
Page views:

Only tabId persists in this tab session. Page views reset every reload.

Storage Management

Tools to manage and debug your persisted data:

Clear Storage

⚠️ These actions will only clear StarHTML persist data from this demo

How Persistence Works

The persist handler is a simple yet powerful Datastar attribute plugin:

Usage Patterns

  • data_persist="signal_name" - Persist a specific signal
  • data_persist="signal1,signal2" - Persist multiple signals
  • data_persist=signal.with_(session=True) - Use sessionStorage
  • data_persist=([signal1], dict(key="mykey")) - Custom storage key
  • Default storage key: starhtml-persist
  • Supports comma or semicolon separated signal names

Implementation Details

  • Loads stored values on element initialization
  • Watches specified signals for changes
  • Debounced writes (500ms) prevent excessive storage calls
  • JSON serialization for complex data types
  • Error handling for storage quota exceeded
  • Fallback behavior when storage is unavailable