fix(astro:transitions): add missing docs for available public APIs

[ArmandPhilippot]

Description (required)

• Updates astro:transitions reference to:

  • Fix <Since /> in <ClientRouter /> (added in v5, Rename the ViewTransitions component to ClientRouter astro#11980)
  • Fix the transitionEnabledOnThisPage type
  • Fix types in "Lifecycle events attributes":
    • info is typed as any and this matches what we describe ("arbitrary data").
    • direction is typed as string (because string is wider than Direction) and using Direction was a bit confusing given the description ("anything else").
  • Add Type:/<Since /> for "Lifecycle events"
  • Add fallback as available prop for <ClientRouter /> (hidden in the ToC)
  • Add default return value for getFallback()
  • Add missing docs for public APIs added in New events for Astro's view transition API astro#9090:
    • createAnimationScope,
    • isTransitionBeforePreparationEvent,
    • isTransitionBeforeSwapEvent,
    • TRANSITION_BEFORE_PREPARATION,
    • TRANSITION_AFTER_PREPARATION,
    • TRANSITION_BEFORE_SWAP,
    • TRANSITION_AFTER_SWAP,
    • TRANSITION_PAGE_LOAD,
    • type NavigationTypeString,
    • type TransitionBeforePreparationEvent,
    • type TransitionBeforeSwapEvent
  • Add docs for type Direction and type Fallback added in API for clientside router astro#8571
  • Add some <ReadMore /> around existing content
  • Specify when the lifecycle event attributes are available (for users not coming from the event itself, this can be confusing without that)
  • Slightly reword some existing content

• Updates "View Transitions" guide to:

  • Add some links to the reference
  • Replace navigate() options with a link (we already document them, the same way, in the reference)
  • Replace the history options link

Not documented

• ClientRouterModule, TransitionModule from astro:transitions: although importable those are internal types
• EventModule, TransitionRouterModule, TransitionSwapFunctionModule from astro:transitions/client: although importable those are internal types
• type Options: I think it makes more sense to details the properties under navigate() so I wasn't sure how to document the type. I left it in the available imports from astro:transitions/client though.
• The TransitionAnimation, TransitionAnimationPair, TransitionAnimationValue, TransitionDirectionalAnimations types (currently partially displayed in the guide) because they are exported from astro, not astro:transitions.

Related issues & labels (optional)

• Suggested label: add new content, improve or update documentation

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Built without sensitive environment variables

Name	Link
🔨 Latest commit	14d134f
🔍 Latest deploy log	https://app.netlify.com/projects/astro-docs-2/deploys/692a133a4b70d40008cebba5
😎 Deploy Preview	https://deploy-preview-12734--astro-docs-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/view-transitions.mdx	Source changed, localizations will be marked as outdated.
en/reference/modules/astro-transitions.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[ArmandPhilippot]

This is probably for Sarah: I struggled a bit to describe the constants (this one and the followings). I'm not sure this is the best description, but I think those are useful to document.

[ArmandPhilippot]

I wasn't sure if this should be plain text or part of the API block, but I think this is helpful to add this information for someone getting there from a direct link, an AI, etc.

[ArmandPhilippot]

Anyone is welcome to review this PR, but I'll ping @matthewp and @martrapp because they know better the view transitions API. If one of you two has the time to check the accuracy of the new sections this would be helpful! No rush!

Context: Some imports weren't documented, at least in the reference page. I added docs for them and fixed some types/since while I was there. The details is available in the first post. You're free to check the whole PR, but your help is especially useful for createAnimationScope() and the direction attribute (see my review comment for why I need you here).

Also, is there a reason for the TransitionAnimation, TransitionAnimationPair, TransitionAnimationValue, TransitionDirectionalAnimations types to be exported from astro instead of astro:transitions?
Not a real issue, I ask the question because it would have been convenient to have them in the same place so that they could be documented on the reference page, and avoid displaying them as a code snippet in the guide.

[martrapp]

Hi @ArmandPhilippot 👋🏼 thank you for taking care and fixing!

I'm afraid, some of these are long forgotten youthful mistakes and which we should mark them as deprecated:

• TRANSITION_AFTER_PREPARATION, TRANSITION_AFTER_SWAP, TRANSITION_BEFORE_PREPARATION, TRANSITION_BEFORE_SWAP, TRANSITION_PAGE_LOAD.
  When I introduced them, Matthew told me that Astro does typically not provide constants like this, but I missed the chance to take them out again.
• isTransitionBeforePreparationEvent, isTransitionBeforeSwapEvent: I found those narrowing function useful for Typescript. That was before I learned from Erika, how this is done right (types/public/view-transitions.ts)

[ArmandPhilippot]

Thanks for the feedback, Martin! Well, even if we end up not documenting them because we prefer to deprecate them, this allows us to identify what we should clean up in a future version! The same thing happened with astro:actions: withastro/astro#14608 😄

[martrapp]

Also, is there a reason for the TransitionAnimation, TransitionAnimationPair, TransitionAnimationValue, TransitionDirectionalAnimations types to be exported from astro instead of astro:transitions?

Good question, that never really stood out to me. @matthewp?

Direction:

Yes, you are right, this can only be changed in a listener for astro:before-preparation.

Details: For links and form submission, direction is automatically set to forward. History traversals set this to forward or back. The value is available in the TransitionBeforePreparationEvent and can be changed using a listener to astro:before-preparation. The value is used to control the animation direction right before astro:before-swap is dispatched. Listeners to astro:before-swap can still read the value, but in that event, it is write protected.

While normal navigation is forward and back, this limits you to two types of animation on navigation. So, yes, an idea was to support more than those two and hence allowing direction to have arbitrary values. We never pushed that much and integration with Astro scopes and the generated styles is very low-level.

Your createAnimationScope example looks good, but I'll need more time to review ;-)

[florian-lefebvre]

Armand feel free to create a new issue on the main repo and assign it to the v6 milestone once you know what we should deprecated/remove!

[martrapp]

Your createAnimationScope example looks good, but I'll need more time to review ;-)

The main benefit of createAnimationScope is that it automatically creates the CSS for the fallback mode when the browser has no native support for view transitions. As of late 2025, current versions of all major browsers have native support.

The method was very niche during the last two years, but now, it might become obsolete. Another deprecation candidate?

[ArmandPhilippot]

I must say I'm late to the party... probably because I'm a Firefox user. 😆 I only try <ClientRouter /> recently and I'm by no mean an expert in view transitions. So, thank you, Martin, for reviewing this, fixing things and giving suggestions for the future of this module!

If I summarize, all the new docs additions (not the small fixes) are no longer relevant and it's probably best to deprecate them? This means:

• createAnimationScope()
• isTransitionBeforePreparationEvent()
• isTransitionBeforeSwapEvent()
• TRANSITION_BEFORE_PREPARATION
• TRANSITION_AFTER_PREPARATION
• TRANSITION_BEFORE_SWAP
• TRANSITION_AFTER_SWAP
• TRANSITION_PAGE_LOAD

Given your explanations this seems reasonable.

I was checking on GitHub the use of createAnimationScope(), and except a certain martrapp 🤔 it seems no one use this. I saw a few imports in other projects, but without actually using it!? So, maybe this one could stay undocumented if we deprecate it.

However, I was able to find a few occurrences for the other ones. So, having docs for them because they exist and are used might be okay for now.

I'll wait a bit before opening an issue on the core repo in case someone more familiar with view transitions in the framework team want to weight on this!

[martrapp]

I was checking on GitHub the use of createAnimationScope(), and except a certain martrapp 🤔 it seems no one use this.

Haha, yes, I also found that one tonight ;-) There might still be some older Firefoxes that benefit from that, but time changes a lot of things.

I'm sorry for he mess you've found and want to thank you very much for looking into this and fixing!