13 · Structure and shell

Persist

LiveView state kept in the browser · sessionStorage or localStorage · on_restore

Keeps a LiveView value in the browser and gives it back (on_restore) when it mounts again.

sessionStorage: survives reloading the tab

0

storage=session · key=showcase_persist_session

.heex
<%!-- sessionStorage: <.persist id key storage="session" value={%{note: @note, count: @count}} on_restore="restore" target={@myself} />
     Escreva, conte, recarregue a página: o valor volta (a aba é a mesma). --%>
<.live_component module={LedgerShowcaseWeb.Demos.PersistDemo} id="persist-session" storage="session" key="showcase_persist_session" />

localStorage: survives closing the tab

0

storage=local · key=showcase_persist_local

.heex
<%!-- localStorage: sobrevive ao fechar a aba (e vale para todas as abas do site) --%>
<.live_component module={LedgerShowcaseWeb.Demos.PersistDemo} id="persist-local" storage="local" key="showcase_persist_local" />

Usage

<.persist id="draft-persist" key="draft" value={@draft} on_restore="restore" />

Rules

  • The value stays in the browser, readable by any script on the page and by the user: do not put tokens, passwords or personal data in it.
  • What comes back through on_restore is user input: validate it in handle_event.
  • Give each stored state its own id and key; storage is session (default) or local.

API reference

Todos os function components, atributos, valores e slots que este componente cobre.

persist/1: keeps a piece of LiveView state in the browser and gives it back when it mounts.

<.persist
  id="agent-widget"
  key="agent_widget"
  storage="session"
  value={%{open: @open?, conversation_id: @cid}}
  on_restore="aw_restore"
/>

def handle_event("aw_restore", %{"value" => %{"open" => open?, "conversation_id" => cid}}, socket),
  do: {:noreply, assign(socket, open?: open?, cid: cid)}

Renders a hidden element; the hook LedgerUI.Persist (priv/static/ledger_ui/hooks/persist.js) writes value (as JSON) under key in sessionStorage or localStorage (storage) on every mounted and updated, unless it did not change.

On mount, when something is saved under key and it differs from the current value, the hook pushes on_restore with %{"value" => saved} before writing, and does not write the current value over it (the server's reply, updated, writes the restored one). So the saved value survives a push_navigate: the next mount restores it. A value that is not valid JSON is ignored (and overwritten by the next write). Storage that is blocked or full is ignored too.

Not a place for secrets {: .warning}

The value stays in the browser (readable by any script of the page and by the user, and in localStorage it outlives the tab). Do not put tokens, passwords or personal data in it, and do not trust it: it is user input when it comes back through on_restore, so validate it in the handle_event.

target is the phx-target of on_restore (a selector or @myself). Give each persisted state its own id and key.

<.persist>

Attr Type Default Values / notes
id (required) :string Needed by the hook.
key (required) :string The storage key.
value (required) :any Anything that encodes to JSON.
storage :string "session" session, local
on_restore :string nil Event pushed with %{"value" => saved}.
target :any nil phx-target of on_restore.

Any other HTML/phx attribute goes to the root element.