Skip to content
Source
Sign inSign up
TanStack/db

Support for Stable ViewKeys to Prevent UI Re-renders on ID Mapping #19

Send to my agent
OpenKyleAMathews(GitHub profile, opens in a new tab) opened this issue 4 comments

Problem

Currently, optimistic inserts use temporary IDs (tempid) until the server responds with the authoritative ID (realid). When the ID changes, React re-renders the keyed element, causing UI issues:

  • Focus loss
  • Component state reset
  • Input interruption
  • Flickering

Because React treats the key as identity, replacing the ID forces React to unmount and remount the component. In many cases this is acceptable, but in advanced usage (e.g., editable lists, interactive forms) it causes UX degradation.

Proposed Solution

Introduce optional developer control to maintain a stable viewKey that survives the tempid → realid mapping.

  • Each record will have a viewKey field generated at optimistic creation time.
  • viewKey remains constant across ID upgrades.
  • UI components should key off viewKey, not id, if stability is required.
  • Expose a manual API for developers to map tempid to realid in the persist function.

Example usage:

persist: (transaction) => {
  const result = api.insert(data);
  transaction.mapViewKey({ tempId: tempid, realId: result.id });
}
  • Mapping must occur after server success but before transaction completion.
  • System updates internal references.
  • No UI re-renders triggered by ID changes.
  • If no mapping is performed, fallback to current behavior (tempid replaced by realid, React re-renders).

Design Principles

  • Opt-in only. No automatic viewKey generation unless explicitly requested.
  • Defaults stay simple for developers who don't need stability.
  • Advanced users can maintain seamless UX where needed.
  • Keeps transaction model deterministic and explicit.

Future Work

  • Consider offering a helper to auto-generate viewKey at insert time if requested.
  • Potentially expose viewKey defaults in the collection or transaction configuration for convenience.
  1. +1 would be super useful and convenient to not have to maintain a manual mapping to avoid rerendering! without this or manual mapping, it makes components with animations that trigger on mount look like a UI bug

    When do you think this will be ready for release?

  2. It's coming — we're just focused on getting query-driven sync production ready atm. In the meantime, you can do something similar yourself https://tanstack.com/db/latest/docs/guides/mutations#solution-3-maintain-a-view-key-mapping

  3. asked about transactions, then ran into this same issue! Excited that it's being worked on. Do you think the view key pattern would be the defacto in the future? Was considering adding client ids to my schema but seems like a big overhead.

  4. @CelesteComet yeah we want to get this in — it's been deprioritized though for a while as we're focused on bug fixing

Sign in to join this conversation.