Skip to content
This repository has been archived by the owner on Jan 1, 2025. It is now read-only.

[Docs] Update react docs link #2228

Open
wants to merge 1 commit into
base: docs
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
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
2 changes: 1 addition & 1 deletion docs/blog/2020-06-18-0.0.10-released.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ function useRecoilCallback<Args, Return>(
): (...Args) => ReturnValue
```

The `useRecoilCallback()` hook is similar to the React [`useCallback()`](https://reactjs.org/docs/hooks-reference.html#usecallback) hook for producing a callback function. But, instead of just providing an input callback function you wrap it with a function providing a callback interface parameter that gives you access to a `Snapshot` and `set()`/`reset()` callbacks to update the current global state. The provided `Snapshot` represents the state when the callback is called, not when the callback function was originally created.
The `useRecoilCallback()` hook is similar to the React [`useCallback()`](https://react.dev/reference/react/useCallback) hook for producing a callback function. But, instead of just providing an input callback function you wrap it with a function providing a callback interface parameter that gives you access to a `Snapshot` and `set()`/`reset()` callbacks to update the current global state. The provided `Snapshot` represents the state when the callback is called, not when the callback function was originally created.

NOTE: This is a slight breaking change in the API, but we are still on version `0.0.x` of Recoil and haven’t fully started semantic versioning yet.

Expand Down
4 changes: 2 additions & 2 deletions docs/blog/2022-01-28-0.6.0-release.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,11 +8,11 @@ Recoil 0.6 introduces improved support for React 18, including concurrent render

## React 18

Recoil 0.6 uses the latest APIs from React 18 for improved safety and performance. This release is compatible with [concurrent rendering](https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html#whats-coming-in-react-18) and [`<React.StrictMode>`](https://reactjs.org/docs/strict-mode.html), which is useful for testing and identifying potential issues for concurrent rendering. Making Recoil and React state changes in the same batch now stay in sync to provided a consistent view of state. Some of these improvements are also available while using previous versions of React. *When experimenting with React 18 please use the latest RC build, as the original React `18.0.0-rc.0` package has a bug that has since been fixed.*
Recoil 0.6 uses the latest APIs from React 18 for improved safety and performance. This release is compatible with [concurrent rendering](https://react.dev/blog/2021/06/08/the-plan-for-react-18#whats-coming-in-react-18) and [`<React.StrictMode>`](https://react.dev/reference/react/StrictMode), which is useful for testing and identifying potential issues for concurrent rendering. Making Recoil and React state changes in the same batch now stay in sync to provided a consistent view of state. Some of these improvements are also available while using previous versions of React. *When experimenting with React 18 please use the latest RC build, as the original React `18.0.0-rc.0` package has a bug that has since been fixed.*

### Concurrent Rendering and Transitions

React 18 offers a new hook [`useTransition()`](https://reactjs.org/docs/concurrent-mode-patterns.html#transitions) for transitioning to a new state while having control over what to render before the new state is ready. Recoil should be compatible with this approach and provides a consistent view with React state. However, React 18 may fallback from concurrent updates and does not yet officially support initiating transitions based on state changes to external stores. This is something the React team is looking into supporting, but until then we have added experimental support for this through the following hooks. This API is considered experimental because there may be use cases we haven’t found which are not handled.
React 18 offers a new hook [`useTransition()`](https://react.dev/reference/react/useTransition) for transitioning to a new state while having control over what to render before the new state is ready. Recoil should be compatible with this approach and provides a consistent view with React state. However, React 18 may fallback from concurrent updates and does not yet officially support initiating transitions based on state changes to external stores. This is something the React team is looking into supporting, but until then we have added experimental support for this through the following hooks. This API is considered experimental because there may be use cases we haven’t found which are not handled.
* `useRecoilState_TRANSITION_SUPPORT_UNSTABLE()`
* `useRecoilValue_TRANSITION_SUPPORT_UNSTABLE()`
* `useRecoilValueLoadable_TRANSITION_SUPPORT_UNSTABLE()`
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/api-reference/core/useRecoilCallback.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: useRecoilCallback(callback, deps)
sidebar_label: useRecoilCallback()
---

This hook is similar to [*`useCallback()`*](https://reactjs.org/docs/hooks-reference.html#usecallback), but will also provide an API for your callbacks to work with Recoil state. This hook can be used to construct a callback that has access to a read-only [`Snapshot`](/docs/api-reference/core/Snapshot) of Recoil state and the ability to asynchronously update current Recoil state.
This hook is similar to [*`useCallback()`*](https://react.dev/reference/react/useCallback), but will also provide an API for your callbacks to work with Recoil state. This hook can be used to construct a callback that has access to a read-only [`Snapshot`](/docs/api-reference/core/Snapshot) of Recoil state and the ability to asynchronously update current Recoil state.

Some motivations for using this hook may include:
* Asynchronously read Recoil state without subscribing a React component to re-render if the atom or selector is updated.
Expand Down Expand Up @@ -31,7 +31,7 @@ function useRecoilCallback<Args, ReturnValue>(
```

* **`callback`** - The user callback function with a wrapper function that provides a callback interface. Callbacks to change the state will be queued to asynchronously update the current Recoil state. The type signature of the wrapped function matches the type signature of the returned callback.
* **`deps`** - An optional set of dependencies for memoizing the callback. Like `useCallback()`, the produced callback will not be memoized by default and will produce a new function with each render. You can pass an empty array to always return the same function instance. If you pass values in the `deps` array a new function will be used if the reference equality of any dep changes. Those values can then be used from within the body of your callback without getting stale. (See [`useCallback`](https://reactjs.org/docs/hooks-reference.html#usecallback)) You can [update eslint](/docs/introduction/installation#eslint) to help ensure this is used correctly.
* **`deps`** - An optional set of dependencies for memoizing the callback. Like `useCallback()`, the produced callback will not be memoized by default and will produce a new function with each render. You can pass an empty array to always return the same function instance. If you pass values in the `deps` array a new function will be used if the reference equality of any dep changes. Those values can then be used from within the body of your callback without getting stale. (See [`useCallback`](https://react.dev/reference/react/useCallback)) You can [update eslint](/docs/introduction/installation#eslint) to help ensure this is used correctly.

### Callback Interface
* **`snapshot`** - The [`Snapshot`](/docs/api-reference/core/Snapshot) provides a read-only look at the Recoil atom state when the snapshot was accessed. While the atom values are static, asynchronous selectors may still resolve. Snapshots will be retained for the duration of sync or async callbacks, but if you store and use it beyond that scope then you need to [explicitly retain it](/docs/api-reference/core/Snapshot#asynchronous-use-of-snapshots).
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/api-reference/core/useRecoilState.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ type SetterOrUpdater<T> = (T | (T => T)) => void;

- `state`: an [`atom`](/docs/api-reference/core/atom) or a _writeable_ [`selector`](/docs/api-reference/core/selector). Writeable selectors are selectors that have both a `get` and `set` in their definition while read-only selectors only have a `get`.

This API is similar to the React [`useState()`](https://reactjs.org/docs/hooks-reference.html#usestate) hook except it takes a Recoil state instead of a default value as an argument. It returns a tuple of the current value of the state and a setter function. The setter function may either take a new value as an argument or an updater function which receives the previous value as a parameter.
This API is similar to the React [`useState()`](https://react.dev/reference/react/useState) hook except it takes a Recoil state instead of a default value as an argument. It returns a tuple of the current value of the state and a setter function. The setter function may either take a new value as an argument or an updater function which receives the previous value as a parameter.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/api-reference/core/useRecoilStateLoadable.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: useRecoilStateLoadable()

This hook is intended to be used for reading the value of asynchronous selectors. This hook will implicitly subscribe the component to the given state.

Unlike [`useRecoilState()`](/docs/api-reference/core/useRecoilState), this hook will not throw an `Error` or `Promise` when reading from an asynchronous selector (for the purpose of working alongside [React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html)). Instead, this hook returns a [`Loadable`](/docs/api-reference/core/Loadable) object for the value along with the setter callback.
Unlike [`useRecoilState()`](/docs/api-reference/core/useRecoilState), this hook will not throw an `Error` or `Promise` when reading from an asynchronous selector (for the purpose of working alongside [React Suspense](https://react.dev/reference/react/Suspense)). Instead, this hook returns a [`Loadable`](/docs/api-reference/core/Loadable) object for the value along with the setter callback.

---

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/api-reference/core/useRecoilTransaction.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ function useRecoilTransaction_UNSTABLE<Args>(
```

* **`callback`** - User callback function with a wrapper function that provides the transaction interface. ***This function must be pure without any side-effects.***
* **`deps`** - An optional set of dependencies for memoizing the callback. Like `useCallback()`, the produced transaction callback will not be memoized by default and will produce a new function with each render. You can pass an empty array to always return the same function instance. If you pass values in the `deps` array, a new function will be used if the reference equality of any dep changes. Those values can then be used from within the body of your callback without getting stale. (See [`useCallback`](https://reactjs.org/docs/hooks-reference.html#usecallback)) You can [update eslint](/docs/introduction/installation#eslint) to help ensure this is used correctly.
* **`deps`** - An optional set of dependencies for memoizing the callback. Like `useCallback()`, the produced transaction callback will not be memoized by default and will produce a new function with each render. You can pass an empty array to always return the same function instance. If you pass values in the `deps` array, a new function will be used if the reference equality of any dep changes. Those values can then be used from within the body of your callback without getting stale. (See [`useCallback`](https://react.dev/reference/react/useCallback)) You can [update eslint](/docs/introduction/installation#eslint) to help ensure this is used correctly.

Transaction Interface:
* **`get`** - Get the current value for the requested Recoil state, reflecting any writes performed earlier in the transaction. This currently only supports synchronous atoms.
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/api-reference/core/useRecoilValueLoadable.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: useRecoilValueLoadable()

This hook is intended to be used for reading the value of asynchronous selectors. This hook will subscribe the component to the given state.

Unlike [`useRecoilValue()`](/docs/api-reference/core/useRecoilValue), this hook will not throw an `Error` or `Promise` when reading from an asynchronous selector (for the purpose of using [React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html)). Instead, this hook returns a [`Loadable`](/docs/api-reference/core/Loadable) object.
Unlike [`useRecoilValue()`](/docs/api-reference/core/useRecoilValue), this hook will not throw an `Error` or `Promise` when reading from an asynchronous selector (for the purpose of using [React Suspense](https://react.dev/reference/react/Suspense)). Instead, this hook returns a [`Loadable`](/docs/api-reference/core/Loadable) object.

Use `useRecoilValueLoadable_TRANSITION_SUPPORT_UNSTABLE()` for experimental support for [React 18 transitions](/docs/guides/transitions) based on mutating Recoil state.

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/basic-tutorial/performance.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ Ideally, components would re-render only when they absolutely have to (when the

## Optimization #1: `React.memo()`

To mitigate the issue of child components re-rendering unnecessarily, we can make use of [`React.memo()`](https://reactjs.org/docs/react-api.html#reactmemo), which memoizes a component based on the **props** passed to that component:
To mitigate the issue of child components re-rendering unnecessarily, we can make use of [`React.memo()`](https://react.dev/reference/react/memo), which memoizes a component based on the **props** passed to that component:

```js
const TodoItem = React.memo(({item}) => ...);
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/asynchronous-data-queries.md
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ function CurrentUserInfo() {

The interface of the selector is the same, so the component using this selector doesn't need to care if it was backed with synchronous atom state, derived selector state, or asynchronous queries!

But, since React render functions are synchronous, what will it render before the promise resolves? Recoil is designed to work with [React Suspense](https://reactjs.org/docs/concurrent-mode-suspense.html) to handle pending data. Wrapping your component with a Suspense boundary will catch any descendants that are still pending and render a fallback UI:
But, since React render functions are synchronous, what will it render before the promise resolves? Recoil is designed to work with [React Suspense](https://react.dev/reference/react/Suspense) to handle pending data. Wrapping your component with a Suspense boundary will catch any descendants that are still pending and render a fallback UI:

```jsx
function MyApp() {
Expand All @@ -77,7 +77,7 @@ function MyApp() {

## Error Handling

But what if the request has an error? Recoil selectors can also throw errors which will then be thrown if a component tries to use that value. This can be caught with a React [`<ErrorBoundary>`](https://reactjs.org/docs/error-boundaries.html). For example:
But what if the request has an error? Recoil selectors can also throw errors which will then be thrown if a component tries to use that value. This can be caught with a React [`<ErrorBoundary>`](https://react.dev/reference/react/Component#catching-rendering-errors-with-an-error-boundary). For example:

```jsx
const currentUserNameQuery = selector({
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/guides/atom-effects.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: Atom Effects
sidebar_label: Atom Effects
---

Atom effects are an API for managing side-effects and synchronizing or initializing Recoil atoms. They have a variety of useful applications such as state persistence, state synchronization, managing history, logging, &c. They are similar to [React effects](https://reactjs.org/docs/hooks-effect.html), but are defined as part of the atom definition, so each atom can specify and compose their own policies. Also check out the [**`recoil-sync`**](/docs/recoil-sync/introduction) library for some implementations of syncing (such as [**URL persistence**](/docs/recoil-sync/url-persistence)) or more advanced use cases.
Atom effects are an API for managing side-effects and synchronizing or initializing Recoil atoms. They have a variety of useful applications such as state persistence, state synchronization, managing history, logging, &c. They are similar to [React effects](https://react.dev/learn/synchronizing-with-effects), but are defined as part of the atom definition, so each atom can specify and compose their own policies. Also check out the [**`recoil-sync`**](/docs/recoil-sync/introduction) library for some implementations of syncing (such as [**URL persistence**](/docs/recoil-sync/url-persistence)) or more advanced use cases.

An *atom effect* is a *function* with the following definition.

Expand Down Expand Up @@ -78,7 +78,7 @@ See [`useGetRecoilValueInfo()`](/docs/api-reference/core/useGetRecoilValueInfo)

### Compared to React Effects

Atom effects could mostly be implemented via React [`useEffect()`](https://reactjs.org/docs/hooks-reference.html#useeffect). However, the set of atoms are created outside of a React context, and it can be difficult to manage effects from within React components, particularly for dynamically created atoms. They also cannot be used to initialize the initial atom value or be used with server-side rendering. Using atom effects also co-locates the effects with the atom definitions.
Atom effects could mostly be implemented via React [`useEffect()`](https://react.dev/reference/react/useEffect). However, the set of atoms are created outside of a React context, and it can be difficult to manage effects from within React components, particularly for dynamically created atoms. They also cannot be used to initialize the initial atom value or be used with server-side rendering. Using atom effects also co-locates the effects with the atom definitions.

```jsx
const myState = atom({key: 'Key', default: null});
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/transitions.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ title: React 18 Transitions
sidebar_label: Transitions
---

[React 18](https://reactjs.org/blog/2021/06/08/the-plan-for-react-18.html) offers a new hook [**`useTransition()`**](https://react.dev/reference/react/useTransition) for transitioning to a new state while having control over what to render before the new state is ready. Recoil should be compatible with this approach and provides a consistent view with React state. However, React 18 may fallback from concurrent updates and does not yet officially support initiating transitions based on state changes to external stores. This is something the React team is looking into supporting, but until then we have added experimental support for this through the following hooks; other hooks should already fully support transitions, so only these variants are necessary. This API is considered experimental because there may be use cases we haven’t found which are not handled.
[React 18](https://react.dev/blog/2021/06/08/the-plan-for-react-18) offers a new hook [**`useTransition()`**](https://react.dev/reference/react/useTransition) for transitioning to a new state while having control over what to render before the new state is ready. Recoil should be compatible with this approach and provides a consistent view with React state. However, React 18 may fallback from concurrent updates and does not yet officially support initiating transitions based on state changes to external stores. This is something the React team is looking into supporting, but until then we have added experimental support for this through the following hooks; other hooks should already fully support transitions, so only these variants are necessary. This API is considered experimental because there may be use cases we haven’t found which are not handled.

- **`useRecoilState_TRANSITION_SUPPORT_UNSTABLE()`**
- **`useRecoilValue_TRANSITION_SUPPORT_UNSTABLE()`**
Expand Down
Loading