View Transition

[GrandSchtroumpf]

What is it about?

Provide an ViewTransition API integrated into Qwik

What's the motivation for this proposal?

Problems you are trying to solve:

ViewTransition needs to run before DOM is updated & wait until DOM is updated, so it's difficult to achieve a good API outside of the framework itself

Goals you are trying to achieve:

Create an Qwik API for ViewTransition.

Any other context or information you want to share:

React just released an API for ViewTransition, let's do the same, but better :)

---

Proposed Solution / Feature

What do you propose?

3 things :

1. An imperative function to start view transition
   This function takes a callback that changes the state and wait for next DOM update

async function startViewTransition(update, { types }) {
 if ('startViewTransition' in document) {
   const transition = document.startViewTransition({
     update: async () => {
       await update();
       await nextDOMUpdate(); // <-- TODO: find most reliable way to wait for next dom update
     },
     types: [...types, 'qwik-update']
   });
   // Integrate with existing events
   document.dispatchEvent(new CustomEvent('qViewTransition', transition));
   return transition;
 } else {
   return update();
 }
}

How to use it :

const counter = useSignal(1);
return <button onClick$={() => startViewTransition(() => counter.value++)}>Add</button>

2. An reactive hook to start view transition:
   This hook will listen on signal, props or store changes and startViewTransition before the DOM is update.

function useViewTransition({ track, types }) {
  // This code need to be integrated with the scheduler to work
}

How to use it :

const counter = useSignal(1);
useViewTransition({
  track: counter,
  types: ['increment'],
})

3. Add an attribute add view-transition-class (Optional)
   This is a shortcut to simplify the use of view-transition-name & view-transition-class

@layer qwik {
  @property --view-transition-name {
    synthax: '<custom-indent>';
    inherits: false;
  }
  [qViewTransitionName] {
    view-transition-name: attr(qViewTransitionName type(<custom-indent>));
  }
  [qViewTransitionClass] {
    view-transition-name: match-element;
    view-transition-class: attr(qViewTransitionClass type(<custom-indent>));
  }
}

How to use it:

return (
  <section>
    <img qViewTransitionName="avatar">
    <ul>
      {list.map(item => <li key={item} qViewTransitionClass="item")}>{item}</li>)}
    </ul>
  </section>
)

Currently Safari & Firefox don't support the attr(... type()), but it's still possible to use style.

Animate with JS

Since startViewTransition & useViewTransition would both emit the qViewTransition event, we can animate with useOnDocument :

useOnDocument('qViewTransition', $((e) => {
  const transition = e.details;
  if (transition.types.includes('increments')) {
    document.animate(...);
  }
}))

Links / References

ViewTransition API doc:
https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API

React API :
https://react.dev/reference/react/ViewTransition

Qwik current integration:
https://qwik.dev/docs/cookbook/view-transition/

[wmertens]

ok nice. I would only implement the class stuff once Safari & Firefox promise to have it.

So the only thing required from the framework is that nextDOMUpdate() call that returns when the currently planned DOM updates have completed, right?

Paging @Varixo for that.

[GrandSchtroumpf]

We need nextDOMUpdate() for startViewTransition() (imperative function) for sure.

For useViewTransition(), I'm not sure. Does useTask$ callback runs before or after DOM updates ?
If it's before we are good, else we would need a way to run useViewTransition before DOM update.

[thejackshelton]

const add = $(() => {
  startViewTransition({
    update: () => percent.value++,
    type: ['increment']
  });
})

I had a similar type of API experimenting this week. My thoughts at the time were that we could avoid a lot of the closure craziness with something like transition$.

const add = transition$(() => {
  percent.value++;
});

onClick$={add}

---

I like the idea of allowing multiple jsx nodes to share view transitions with the qViewTransition attribute, although the naming IMO could be more intuitive. React uses a share prop that takes a string, maybe we could have something similar? Or name is something like transition

And if it's a basic view transition like an enter and exit animation I don't think a name is needed, the framework or API could generate the name for you. That's another benefit of transition$

Transition types could be handled like this, then there is no need for a hook at all, and you can place the function anywhere

export default component$(() => {
  const count = useSignal(0);
  
  const increment = transition$(() => {
    count.value++;
  }, { types: ['increment'] });
  
  const decrement = transition$(() => {
    count.value--;
  }, { types: ['decrement'] });
  
  return (
    <div>
      <div>{count.value}</div>
      <button onClick$={increment}>+</button>
      <button onClick$={decrement}>-</button>
    </div>
  );
});

Then later in CSS:

/* Slide up when incrementing */
html:has-view-transition-type(increment) ::view-transition-new(root) {
  animation: slide-up 0.3s;
}

/* Slide down when decrementing */
html:has-view-transition-type(decrement) ::view-transition-new(root) {
  animation: slide-down 0.3s;
}

[thejackshelton]

Even conditional types, like:

const increment = transition$(() => {
  count.value++;
}, { 
  types: ['increment', count.value >= 100 ? 'milestone' : null].filter(Boolean)
});

This makes animation more dynamic and easy to use

[GrandSchtroumpf]

I agree, transition$ would be a better user experience. We could have a lower level startViewTransition function that is used in both transition$ and useViewTransition :)

[GrandSchtroumpf]

Here is a stackblitz to test transition$ and useViewTransition:
https://stackblitz.com/edit/vitejs-vite-dyda5a24?file=src%2Fapp.tsx

• transition$ works well. I used setTimeout(res, 10) to wait for next DOM update, it was more reliable that requestAnimationFrame & queueMicroTask
• useViewTransition doesn't work with useTask$, so we would need to find a way to run the code before the DOM is updated.

[thejackshelton]

Forwarding a discussion from discord:

View Transition API Design

Proposals Discussed

**1. transition$ + Derived transition state

• Two APIs: one for imperative actions, one for reactive computed state
• Mirrors useComputed$ pattern for consistency

2. transition$ + useTransition()

• useTransition() creates a signal that auto-transitions on every write
• Opt-out via signal.transition = false flag

3. transition$ alone

• Single primitive that composes with existing Qwik patterns (useTask$, useResource$)

Key Arguments

Jack's Position (transition$ alone):

• Most transitions are directly correlated to events (button clicks, form submits)
• Composes naturally with useTask$ for reactive cases
• No new reactivity abstractions - avoids confusion
• Transitions decorate HOW updates happen, not WHAT the data is (mutation vs derivation)
• Supports async patterns (useTask$ + async)
• Believes computed transitions are rare in practice, wants more conclusive evidence it is a pain point.

Grand's Position (transition$ + Derived transition state):

• Better DX for derived/computed state that transitions
• Matches useComputed$ pattern users already know, is more intuitive for reactivity
• Avoids manual state management for transitions
• Qwik would be first framework with truly reactive view transitions
• Concerns about extra state and complexity with having only transition$ alone

Critical Technical Points

1. useComputedView$ or computed transitions cannot support auto tracking (context breaks on await)
2. Most real cases need coordination logic anyway (works already using useTask$, not a consensus on DX)
3. Transitions ≠ Derivation: View transitions don't transform data, they animate updates

Approaches Considered

Approach A: Start with transition$ alone

// Imperative
const add = transition$(() => {
  todos.value = [...todos.value, newTodo.value];
});

// Reactive via composition
useTask$(async ({ track }) => {
  track(() => messages.value);
  await handleNewMessage();
});

• Minimal API surface
• Composes with existing patterns
• Add useComputedView$ later if needed

Approach B: Ship both transition$ + Derived transitions from start

// Imperative
const add = transition$(() => {...});

// Reactive computed
const filtered = useComputedView$(() => list.value.filter(...));

• More ergonomic for computed state
• Higher API cost upfront
• May ship in community library first to validate need

Approach C: Explore signal-level transitions

• Make signals themselves transition-aware
• Setter function wraps updates in startViewTransition
• Needs more technical exploration

Open Questions

• How common are computed transitions in real applications?
• Can we make signal setters transition-aware?
• Should computed transition helpers live in core or community initially?

[GrandSchtroumpf]

I did some test with useTask & useComputed$, the issue is that document.startViewTransition takes time to start, so we won't be able to run it on state update:

const logChanges = () => {
  const before = document.querySelectorAll('li').length;
  setTimeout(() => {
    const after = document.querySelectorAll('li').length;
    console.log(`${before}, ${after}`);
  }, 10);
}

export default component$(() => {
  const list = useStore<number[]>([]);

  const add = $(() => {
    list.push(Math.random())
  });

  useTask$(({ track }) => {
    track(list);
    if (isBrowser) {
      document.startViewTransition(logChanges); // logs 1,1 2,2 3,3
      logChanges(); // logs 0,1 1,2 2,3
    }
    return list;
  })

  return (
    <div>
      <ul>
        {list.map((item) => (
          <li key={item}>{item}</li>
        ))}
      </ul>
      <button onClick$={add}>Add</button>
    </div>
  );
});

Which also mean that updating state through transition$ will delay by 1 frame the time it takes to actually update the state.

---

I think transition$ is a nice wrapper around the native startViewTransition. I don't think this should be in core though since it's "just" a wrapper.
Concerning the name, I think viewTransition$ would be more explicit.
Also I think it should support a root option to support future scope view transition:
https://developer.chrome.com/blog/scoped-view-transitions-feedback

interface ViewTransitionOptions {
  update?: () => any;
  types?: string[];
  root?: string || Element;
}
export function startViewTransition(options: ViewTransitionOptions = {}) {
  const {
    update = () => null,
    types = [],
    root = document
  } = options;
  if ('startViewTransition' in document) {
    let transition;
    const element = typeof root === 'string' ? document.getElementById(root) : root;
    try {
      transition = element.startViewTransition({
        update: async () => {
          if (update) await update();
          await nextDOMUpdate();
        },
        types: ['qwik', ...types],
      });
    } catch {
      // For browsers that don't support types
      transition = document.startViewTransition(async () => {
        if (update) await update();
        await nextDOMUpdate();
      });
    }
    document.dispatchEvent(
      new CustomEvent('qViewTransition', { detail: transition })
    );
    return transition;
  } else {
    // For browsers that don't support view transition api
    if (update) return update();
  }
}
function viewTransitionQrl<T extends any[]>(
  qrl: QRL<(...args: T) => any>,
  options?: Omit<ViewTransitionOptions, update>
) {
  return $((...args: T) => {
    return startViewTransition({ update: () => qrl(...args), ...options });
  });
}
export const viewTransition$ = implicit$FirstArg(viewTransitionQrl);

---

I still think that a reactive API would be a better experience, like the <AnimatePresence/> API from motion:
https://motion.dev/docs/react-animate-presence

Unfortunately, it would mean having a task blocking rendering :

useBlockingTask$(async ({ track }) => {
  track(signal);
  return new Promise(res => document.startViewTransition(res));
});

This kind of API would open the door to a LOT of animation capabilities (not only ViewTransition). But I understand this might be a big update.

---

Which leads to my conclusion :
Let's start with viewTransition$ and discuss the possibility of a useBlockingTask$ in another discussion

[thejackshelton]

useTask$ already blocks rendering the moment a promise is returned / awaited. It's parallel if you do not await the promise. This is by design from Misko. There is a in-depth video on it you could ask Shai for.

That is why the pattern I was proposing:

  useTask$(async ({ track }) => {
    track(() => count.value);

    // if is adding
    await add(); <--- add being transition$ / whatever we want to name it

    // if is removing
    // do remove
  });

Just works, no setTimeout needed. If that isn't clear then I think we need some sort of linter error on floating promises if we don't already have one.

Also list is a store object, I don't think you can track store objects 🤔

[thejackshelton]

I think your example it would be something like this:

useTask$(async ({ track }) => {
  track(signal);
  await document.startViewTransition(() => {
    // DOM updates happen here (or can be empty)
  }).finished;
});

[GrandSchtroumpf]

Ok, so it works on v1 but not on v2.
Here is the API :

useViewTransitionTask$(({ track, runTransition }) => {
  track(list);
  // Optional callback to run transition with JS
  runTansition(async (transition) => {
    await transition.ready;
    document.documentElement.animate(...);
  })
}, {
  types: ['increment']
})

And here is the implementation:

interface ViewTransitionTask {
  track: (fn: (() => Object) | Object) => any;
  runTransition: (fn: (transition: any) => any) => any;
}

export function useViewTransitionTaskQrl(
  qrl: QRL<(task: ViewTransitionTask) => void>,
  options: Omit<ViewTransitionOptions, 'update'> = {}
) {
  const runTransitionFn = useConstant<any>({ call: undefined });
  useTask$(async (task) => {
    await new Promise<void>((res) => {
      const runTransition = (fn: (transition: any) => any) => {
        runTransitionFn.call = fn;
      };
      const track = (tracker: (() => Object) | Object) => {
        const next = task.track(tracker);
        if (next === null) return res();
        const transition = startViewTransition({
          update: res,
          types: options.types,
          root: options.root,
        });
        if (runTransitionFn.call) runTransitionFn.call(transition);
      };
      qrl({ runTransition, track });
    });
  });
}
export const useViewTransitionTask$ = implicit$FirstArg(
  useViewTransitionTaskQrl
);

Let me know if you've got some feedback on the naming or API design.
Here is a working stackblitz (in v1 since v2 doesn't work yet):
https://stackblitz.com/edit/vitejs-vite-dyda5a24?file=src%2Fapp.tsx

[GrandSchtroumpf]

@thejackshelton @wmertens the APIs are working on v1 (blocked by a bug in v2) with no update required on core.
Would you rather have it :

1. Included in core package
2. Included in core repo as a separate package
3. External library

[maiieul]

4th option can be to publish it as an experimental API. This sounds to me like it should eventually be part of core – the implementation being quite low level. The benefit of being an experimental API is that it would bring more awereness and feedback.

[GrandSchtroumpf]

It's not very low level, in its most simple form it looks like that:

const transitionQrl = (qrl) => document.startViewTransition(qrl);
export const transition$ = implicit$FirstArg(transitionQrl);

const useTransitionTask$ = (track) => {
  useTask$(async (task) => {
    task.track(track);
    await new Promise(res => startViewTransition(res));
  })
}

[thejackshelton]

I'm personally more a fan of transition$ and useTransitionTask$ since you're already using javascript so it is implied that it is a view transition. Also the point of abstracting in the first place is making the view transitions api easier to deal with.

I think the fact that it's view transitions are more of an implementation detail. Also how often is it that someone is going to use the WAAPI to animate something in a task? I can't imagine that would be a common use case. And also we have two different names for the same thing here viewTransition$ and runTranstion. If the API were to be kept the way it currently is then it should be outside of core IMO.

Isn't the callback to useTransitionTask$ supposed to be calling runTransition under the hood? If not I don't see the point of useTransitionTask$ over doing it with a useTask$, it is syntactic sugar.

useTransitionTask$(({ track }) => {
  track(list);
  // Transition happens automatically when list changes
}, { types: ['increment'] });

[GrandSchtroumpf]

Ok for the naming.
transition$ is already syntactic sugar, it's basically const transitionQrl = (qrl) => document.startViewTransition(qrl); ^^

runTransition is a callback to run WAAPI transition instead of CSS default animation. So if you use CSS transition you don't need to register the callback.

There are so many use cases for WAAPI:

• Staggering animation: Since ::view-transition-group are flatten at the :root, you cant use sibling-index() to increment animation-delay
• Get the position of a target to update transform-origin
• Animate only element that are visible on the screen at the time of the animation
• Running classic animation alongside the transition