Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Stabilize APIs #9980

Open
wants to merge 4 commits into
base: dev
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Adopt stabilized VT and flushSync apis
  • Loading branch information
brophdawg11 committed Sep 12, 2024
commit 983d548fa3071c33eb8e672570ae38b96a3d4c1b
4 changes: 2 additions & 2 deletions docs/components/form.md
Original file line number Diff line number Diff line change
Expand Up @@ -95,9 +95,9 @@ If true, it will submit the form with the browser instead of client side routing

This is recommended over [`<form>`][form_element]. When the `action` prop is omitted, `<Form>` and `<form>` will sometimes call different actions depending on what the current URL is since `<form>` uses the current URL as the default, but `<Form>` uses the URL for the route the form is rendered in.

### `unstable_viewTransition`
### `viewTransition`

The `unstable_viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in [`document.startViewTransition()`][document-start-view-transition]. If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state].
The `viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in [`document.startViewTransition()`][document-start-view-transition]. If you need to apply specific styles for this view transition, you will also need to leverage the [`useViewTransitionState()`][use-view-transition-state].

<docs-warning>
Please note that this API is marked unstable and may be subject to breaking changes without a major release.
Expand Down
12 changes: 6 additions & 6 deletions docs/components/link.md
Original file line number Diff line number Diff line change
Expand Up @@ -185,24 +185,24 @@ function SomeComp() {

This state is inaccessible on the server as it is implemented on top of [`history.state`][history-state].

## `unstable_viewTransition`
## `viewTransition`

The `unstable_viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in [`document.startViewTransition()`][document-start-view-transition]:
The `viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in [`document.startViewTransition()`][document-start-view-transition]:

```jsx
<Link to={to} unstable_viewTransition>
<Link to={to} viewTransition>
Click me
</Link>
```

If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state]:
If you need to apply specific styles for this view transition, you will also need to leverage the [`useViewTransitionState()`][use-view-transition-state]:

```jsx
function ImageLink(to) {
const isTransitioning =
unstable_useViewTransitionState(to);
useViewTransitionState(to);
return (
<Link to={to} unstable_viewTransition>
<Link to={to} viewTransition>
<p
style={{
viewTransitionName: isTransitioning
Expand Down
12 changes: 6 additions & 6 deletions docs/components/nav-link.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,10 +55,10 @@ a.pending {

### `.transitioning`

A `transitioning` class is added to a [`<NavLink unstable_viewTransition>`][view-transition-prop] component when it is transitioning during a navigation, so you can use CSS to style it.
A `transitioning` class is added to a [`<NavLink viewTransition>`][view-transition-prop] component when it is transitioning during a navigation, so you can use CSS to style it.

```tsx
<NavLink to="/messages" unstable_viewTransition />
<NavLink to="/messages" viewTransition />
```

```css
Expand Down Expand Up @@ -136,9 +136,9 @@ Adding the `caseSensitive` prop changes the matching logic to make it case-sensi
| `<NavLink to="/SpOnGe-bOB" />` | `/sponge-bob` | true |
| `<NavLink to="/SpOnGe-bOB" caseSensitive />` | `/sponge-bob` | false |

## `unstable_viewTransition`
## `viewTransition`

The `unstable_viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in [`document.startViewTransition()`][document-start-view-transition]. By default, during the transition a [`transitioning` class][transitioning-class] will be added to the [`<a>` element][a-element] that you can use to customize the view transition.
The `viewTransition` prop enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in [`document.startViewTransition()`][document-start-view-transition]. By default, during the transition a [`transitioning` class][transitioning-class] will be added to the [`<a>` element][a-element] that you can use to customize the view transition.

```css
a.transitioning p {
Expand All @@ -151,7 +151,7 @@ a.transitioning img {
```

```tsx
<NavLink to={to} unstable_viewTransition>
<NavLink to={to} viewTransition>
<p>Image Number {idx}</p>
<img src={src} alt={`Img ${idx}`} />
</NavLink>
Expand All @@ -160,7 +160,7 @@ a.transitioning img {
You may also use the [`className`][class-name-prop]/[`style`][style-prop] props or the render props passed to [`children`][children-prop] to further customize based on the `isTransitioning` value.

```tsx
<NavLink to={to} unstable_viewTransition>
<NavLink to={to} viewTransition>
{({ isTransitioning }) => (
<>
<p
Expand Down
4 changes: 2 additions & 2 deletions docs/hooks/use-fetcher.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,9 +119,9 @@ fetcher.load("/some/route?foo=bar");

`fetcher.load`'s revalidate by default after action submissions and explicit revalidation requests via [`useRevalidator`][userevalidator]. Because `fetcher.load` loads a specific URL they don't revalidate on changes to route param or URL search param. You can use [`shouldRevalidate`][shouldrevalidate] to optimize which data should be reloaded.

#### `options.unstable_flushSync`
#### `options.flushSync`

The `unstable_flushSync` option tells React Router DOM to wrap the initial state update for this `fetcher.load` in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]. This allows you to perform synchronous DOM actions immediately after the update is flushed to the DOM.
The `flushSync` option tells React Router DOM to wrap the initial state update for this `fetcher.load` in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]. This allows you to perform synchronous DOM actions immediately after the update is flushed to the DOM.

<docs-warning>`ReactDOM.flushSync` de-optimizes React and can hurt the performance of your app.</docs-warning>

Expand Down
6 changes: 3 additions & 3 deletions docs/hooks/use-navigate.md
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,9 @@ navigate(".", {
- `"route"` will use the route hierarchy so `".."` will remove all URL segments of the current route pattern while `"path"` will use the URL path so `".."` will remove one URL segment
- **state**: any - adds persistent client side routing state to the next location
- **preventScrollReset**: boolean - if you are using [`<ScrollRestoration>`][scroll-restoration], prevent the scroll position from being reset to the top of the window when navigating
- **unstable_flushSync**: boolean - wraps the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]
- **unstable_viewTransition**: boolean - enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`
- If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state]
- **flushSync**: boolean - wraps the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]
- **viewTransition**: boolean - enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`
- If you need to apply specific styles for this view transition, you will also need to leverage the [`useViewTransitionState()`][use-view-transition-state]

[redirect]: ../utils/redirect
[flush-sync]: https://react.dev/reference/react-dom/flushSync
Expand Down
6 changes: 3 additions & 3 deletions docs/hooks/use-submit.md
Original file line number Diff line number Diff line change
Expand Up @@ -76,9 +76,9 @@ Options for the submission, the same as [`<Form>`][form-component] props. All op
- **preventScrollReset**: Prevents the scroll position from being reset to the top of the window when the data is submitted. Default is `false`.
- **replace**: Replaces the current entry in the history stack, instead of pushing the new entry. Default is `false`.
- **relative**: Defines relative route resolution behavior. Either `"route"` (relative to the route hierarchy) or `"path"` (relative to the URL).
- **unstable_flushSync**: Wraps the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]
- **unstable_viewTransition**: Enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`
- If you need to apply specific styles for this view transition, you will also need to leverage the [`unstable_useViewTransitionState()`][use-view-transition-state]
- **flushSync**: Wraps the initial state update for this navigation in a [`ReactDOM.flushSync`][flush-sync] call instead of the default [`React.startTransition`][start-transition]
- **viewTransition**: Enables a [View Transition][view-transitions] for this navigation by wrapping the final state update in `document.startViewTransition()`
- If you need to apply specific styles for this view transition, you will also need to leverage the [`useViewTransitionState()`][use-view-transition-state]

```tsx
submit(data, {
Expand Down
16 changes: 8 additions & 8 deletions docs/hooks/use-view-transition-state.md
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
---
title: unstable_useViewTransitionState
title: useViewTransitionState
toc: false
---

# `unstable_useViewTransitionState`
# `useViewTransitionState`

This hook returns `true` when there is an active [View Transition][view-transitions] to the specified location. This can be used to apply finer-grained styles to elements to further customize the view transition. This requires that view transitions have been enabled for the given navigation via the `unstable_viewTransition` prop on the [`Link`][link-component-view-transition] (or the [`Form`][form-component-view-transition], [`NavLink`][nav-link-component-view-transition], `navigate`, or `submit` call).
This hook returns `true` when there is an active [View Transition][view-transitions] to the specified location. This can be used to apply finer-grained styles to elements to further customize the view transition. This requires that view transitions have been enabled for the given navigation via the `viewTransition` prop on the [`Link`][link-component-view-transition] (or the [`Form`][form-component-view-transition], [`NavLink`][nav-link-component-view-transition], `navigate`, or `submit` call).

Consider clicking on an image in a list that you need to expand into the hero image on the destination page:

```jsx
function NavImage({ src, alt, id }) {
const to = `/images/${idx}`;
const vt = unstable_useViewTransitionState(href);
const vt = useViewTransitionState(href);
return (
<Link to={to} unstable_viewTransition>
<Link to={to} viewTransition>
<img
src={src}
alt={alt}
Expand All @@ -28,6 +28,6 @@ function NavImage({ src, alt, id }) {
```

[view-transitions]: https://developer.mozilla.org/en-US/docs/Web/API/View_Transitions_API
[link-component-view-transition]: ../components/link#unstable_viewtransition
[form-component-view-transition]: ../components/form#unstable_viewtransition
[nav-link-component-view-transition]: ../components/nav-link#unstable_viewtransition
[link-component-view-transition]: ../components/link#viewtransition
[form-component-view-transition]: ../components/form#viewtransition
[nav-link-component-view-transition]: ../components/nav-link#viewtransition