Document View Transition events fields

[Fryuni]

📚 Subject area/topic

View Transitions

📋 Suggested page

Either on the View Transitions page (https://docs.astro.build/en/guides/view-transitions/#lifecycle-events) or on some reference page

📋 General description or bullet points (if proposing new content)

Document the type of the View Transition events, which fields are available and what each of them represent.

astro:page-load, astro:after-preparation and astro:after-swap have no special field and are the most used events, this may lead users to incorrectly assume that none of the events have special properties.

Both astro:before-preparation and astro:before-swap have the following properties:

• from: URL: The URL of the page initiating the transition.
• to: URL: The URL transitioning to. (can be modified)
• direction: Direction | string: Direction of the transition, used to change to a different animation when going back in history.
• navigationType: NavigationTypeString: What kind of history navigation is being applied
  • push: New URL is added to the history
  • replace: New URL replaces the previous URL in the history
  • traverse: History remains unchanged, transition is moving through the history
• sourceElement: Element | undefined: Element that triggered the navigation, if it came from a DOM element. This is undefined when the navigations was initiated from the navigate API.
• info: any: ?? Unclear to me where this comes from, requires some investigation.
• newDocument: Document: Content that will be swapped in place of the current document (document.documentElement).

astro:before-preparation also has:

• formData: FormData | undefined: The data that will be sent on the request to load the next page if a form action triggered the navigation.
• loader: () => Promise<void>: The function that runs the next phase of the transition (loading the next page). Can be overridden to add extra behavior or to prevent the execution of the next phase.

astro:before-swap also has:

• viewTransition: ViewTransition: The View Transition element that allows you to hook into it's promises. On browsers that don't have native VT this will be an object implementing the same API.
• swap: () => void: The function that runs the next phase of the transition (swapping the new document in place of the old document). Can be overridden to add extra behavior or to prevent the execution of the next phase.

[sarah11918]

Seems like a job for @martrapp to weigh in on? Martin, can you provide clarity/guidance here for whatever might be missing from docs perspective, and confirm that we have an exhaustive list here?

Then, would be happy to receive a PR to docs to document these properties!

[martrapp]

Hi @sarah11918, thank you for pinging!

As @fryuni said, it would be good to have the event's properties and there purpose defined in the docs. Especially because they are already partly used in the examples. As discussed on discord, it might make sense to have the description in the reference section.

As nobody knows the view transition events better than @Fryuni, I can of course confirm that the list was exhaustive when the issue was opened. A new signal property was just added last week.

• signal: AbortSignal was added for both before-* events.
  Loaders can hook on this property to abort long running asynchronous work like fetch() Swaps can also observe the signal. A new navigation should always have precedence over the current one

What I also can add, as it may be less obvious:

• Astro's built-in animations support forward and back as value for directions. Other values are possible, but require some additional way to generate the necessary CSS.

• The info property has been added to mimic the NavigateEvent property of the same name in the Navigation API.

I would be happy to help with a PR, but I won't open one myself on this topic, as there are certainly better technical writers than me ;-)

[Fryuni]

I would be happy to help with a PR, but I won't open one myself on this topic, as there are certainly better technical writers than me ;-)

Me as well! I'm happy to help, but there are better writers.

[Fryuni]

Well, I can try writing something and then an actual good writer can make it readable 😆

[sarah11918]

Go for it!! I have faith in you! (And, I have a red pen if that faith is misplaced...)

[sarah11918]

ASIDE: @martrapp I see that this PR was released but with no changeset or docs, so I never saw it before merging. Is this also something we need to factor in to new view transitions docs? https://github.com/withastro/astro/pull/10908

[martrapp]

Is this also something we need to factor in to new view transitions docs?

Once we make that "official" it would fit well to the description of the swap function in the astro:before-swap event

[sarah11918]

Just jumping back in here @martrapp and @Fryuni - anyone still want to do anything for me?? 😄

[Fryuni]

Sorry Sarah 🫣

This is on my queue, it just has been moving slowly. I've started catching up on all my pending OSS work yesterday.

So it will come!

_{But I'm not stopping anyone from writing this before me}

[martrapp]

Once we make that "official" it would fit well to the description of the swap function in the astro:before-swap event

see #9084

[bholmesdev]

Thanks for starting this thread! We wanted to explain the navigate() function exposed by astro:transitions, but realized there's no proper API reference (only a guide).

It sounds like we're exploring an API reference in this PR already. I think we should include astro:transitions/client in that!