pmndrs / pmndrs/react-spring

useTransition API rewrite

Open
#2,540 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

area: core kind: request release: major
Dominant language
TypeScript
Stars
29.1k
Forks
1.2k
PR merge metrics
No merged PRs in 30d

Description

A clear and concise description of what the feature is

Rewrite useTransition (packages/core/src/hooks/useTransition.tsx) around a declarative enter/leave model — presence made explicit, "obvious on first read" — without the render-prop bookkeeping it has today:

// today — you index into a render prop, and it's unclear where `item` comes from
const transitions = useTransition(items, {
  keys: item => item.id,
  from: { opacity: 0 },
  enter: { opacity: 1 },
  leave: { opacity: 0 },
})
return transitions((style, item) => (
  <animated.div style={style}>{item.text}</animated.div>
))

Would also subsume #2136 (per-property configs should fall out of the new model rather than be bolted on).

Why should this feature be included?

useTransition is the library's most-reported source of confusion — the same friction recurs across years:

  • #665 (2019) — the API was called "a little weird": users "see item down in the view section and don't know where it comes from."
  • #1281 (2021) — confusion over where state fits once the API takes items.
  • #1711 (discussion) — "how do I make it wait so the leave transition can have an effect?" — exit timing isn't discoverable.
Related issues
  • #1955 — <Presence> component; the enter/exit primitive a cleaner useTransition unlocks.
  • #1628 — persisting/animating components across route changes; a real-world presence use case (its shared-layout half maps to layoutId, tracked separately).
Scope / non-goals
  • The exact new API shape is what this issue is to settle.
  • It must keep react-spring's model: you own the springs and the new API orchestrates them. Presence must not become props on animated.* that create/own springs internally — that inverts the model (see the reasoning on #1826).

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with packages/core/src/hooks/useTransition.tsx and read the linked discussions #2136, #1826, #1955, and #1628 for the current constraints and use cases. First settle an explicit declarative enter/leave API, then verify that it preserves react-spring’s model of user-owned springs and addresses presence and per-property configuration without defining the final API in this issue.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.