Support for Stable ViewKeys to Prevent UI Re-renders on ID Mapping #19
Send to my agentProblem#
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
viewKeyfield generated at optimistic creation time. viewKeyremains constant across ID upgrades.- UI components should key off
viewKey, notid, if stability is required. - Expose a manual API for developers to map
tempidtorealidin 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.
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
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.
@CelesteComet yeah we want to get this in — it's been deprioritized though for a while as we're focused on bug fixing
KyleAMathews(GitHub profile, opens in a new tab) linked this to #734
Sign in to join this conversation.
+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?