Document view transitions (#158)

* Document view transitions Introduced in hotwired/turbo#935 and hotwired/turbo#1007 * Better css example Co-authored-by: Dom Christie <[email protected]> * Add data-turbo-visit-direction to attributes reference * Be more precise Co-authored-by: Dom Christie <[email protected]> * Document meta tag * Clarify it’s optional Co-authored-by: Kevin McConnell <[email protected]> --------- Co-authored-by: Dom Christie <[email protected]> Co-authored-by: Kevin McConnell <[email protected]>
hotwired · Feb 7, 2024 · ccb5744 · ccb5744
1 parent 704ca23
commit ccb5744
Show file tree

Hide file tree

Showing 2 changed files with 26 additions and 0 deletions.
diff --git a/_source/handbook/02_drive.md b/_source/handbook/02_drive.md
@@ -186,6 +186,30 @@ import { Turbo } from "@hotwired/turbo-rails"
 Turbo.session.drive = false
 ```
 
+## View transitions
+
+In [browsers that support](https://caniuse.com/?search=View%20Transition%20API) the [View Transition API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API) Turbo can trigger view transitions when navigating between pages.
+
+Turbo triggers a view transition when both the current and the next page have this meta tag:
+
+```
+<meta name="view-transition" content="same-origin" />
+```
+
+Turbo also adds a `data-turbo-visit-direction` attribute to the `<html>` element to indicate the direction of the transition. The attribute can have one of the following values:
+
+- `forward` in advance visits.
+- `back` in restoration visits.
+- `none` in replace visits.
+
+You can use this attribute to customize the animations that are performed during a transition:
+
+```css
+html[data-turbo-visit-direction="forward"]::view-transition-old(sidebar):only-child {
+  animation: slide-to-right 0.5s ease-out;
+}
+```
+
 ## Displaying Progress
 
 During Turbo Drive navigation, the browser will not display its native progress indicator. Turbo Drive installs a CSS-based progress bar to provide feedback while issuing a request.

diff --git a/_source/reference/attributes.md b/_source/reference/attributes.md
@@ -29,6 +29,7 @@ The following attributes are automatically added by Turbo and are useful to dete
 
 * `disabled` is added to the form submitter while the form request is in progress, to prevent repeat submissions.
 * `data-turbo-preview` is added to the `html` element when displaying a [preview](/handbook/building#detecting-when-a-preview-is-visible) during a Visit.
+* `data-turbo-visit-direction` is added to the `html` element during a visit, with a value of `forward` or `back` or `none`, to indicate its direction.
 * `aria-busy` is added to `html` and `turbo-frame` elements when a navigation is in progress.
 
 ## Meta Tags
@@ -38,5 +39,6 @@ The following `meta` elements, added to the `head`, can be used to customize cac
 * `<meta name="turbo-cache-control">` to [opt out of caching](/handbook/building#opting-out-of-caching).
 * `<meta name="turbo-visit-control" content="reload">` will perform a full page reload whenever Turbo navigates to the page, including when the request originates from a `<turbo-frame>`.
 * `<meta name="turbo-root">` to [scope Turbo Drive to a particular root location](/handbook/drive#setting-a-root-location).
+* `<meta name="view-transition" content="same-origin">` to trigger view transitions on browsers that support the [View Transition API](https://caniuse.com/view-transitions).
 * `<meta name="turbo-refresh-method" content="morph">` will configure [page refreshes with morphing](/handbook/page_refreshes.html).
 * `<meta name="turbo-refresh-scroll" content="preserve">` will enable [scroll preservation during page refreshes](/handbook/page_refreshes.html).