diff --git a/docs/recipes/atom-with-broadcast.mdx b/docs/recipes/atom-with-broadcast.mdx index d9856efba2..39c3bf5b2a 100644 --- a/docs/recipes/atom-with-broadcast.mdx +++ b/docs/recipes/atom-with-broadcast.mdx @@ -1,11 +1,9 @@ --- title: atomWithBroadcast -nav: 8.08 +nav: 8.09 keywords: creators,broadcast --- -## atomWithBroadcast - > `atomWithBroadcast` creates an atom. The atom will be shared between > browser tabs and frames, similar to `atomWithStorage` but with the > initialization limitation. diff --git a/docs/recipes/atom-with-compare.mdx b/docs/recipes/atom-with-compare.mdx index 9649e30bc7..4b148b70da 100644 --- a/docs/recipes/atom-with-compare.mdx +++ b/docs/recipes/atom-with-compare.mdx @@ -4,8 +4,6 @@ nav: 8.05 keywords: creators,compare --- -## atomWithCompare - > `atomWithCompare` creates atom that triggers updates when custom compare function `areEqual(prev, next)` is false. This can help you avoid unwanted re-renders by ignoring state changes that don't matter to your application. diff --git a/docs/recipes/atom-with-debounce.mdx b/docs/recipes/atom-with-debounce.mdx index ec81caf932..e6726b740b 100644 --- a/docs/recipes/atom-with-debounce.mdx +++ b/docs/recipes/atom-with-debounce.mdx @@ -1,11 +1,9 @@ --- title: atomWithDebounce -nav: 8.09 +nav: 8.10 keywords: creators,debounce --- -## atomWithDebounce - > `atomWithDebounce` helps with creating an atom where state set should be debounced. This util is useful for text search inputs, where you would like to call **functions in derived atoms only once** after waiting for a duration, instead of firing an action on every keystroke. diff --git a/docs/recipes/atom-with-listeners.mdx b/docs/recipes/atom-with-listeners.mdx index 6bbdc94e1d..0194553681 100644 --- a/docs/recipes/atom-with-listeners.mdx +++ b/docs/recipes/atom-with-listeners.mdx @@ -1,11 +1,9 @@ --- title: atomWithListeners -nav: 8.07 +nav: 8.08 keywords: creators,listeners --- -## atomWithListeners - > `atomWithListeners` creates an atom and a hook. The hook can be called to > add a new listener. The hook takes as an argument a callback, and that > callback is called every time the atom's value is set. The hook also diff --git a/docs/recipes/atom-with-refresh-default.mdx b/docs/recipes/atom-with-refresh-and-default.mdx similarity index 93% rename from docs/recipes/atom-with-refresh-default.mdx rename to docs/recipes/atom-with-refresh-and-default.mdx index f85dfe5aaf..ed60572358 100644 --- a/docs/recipes/atom-with-refresh-default.mdx +++ b/docs/recipes/atom-with-refresh-and-default.mdx @@ -1,12 +1,10 @@ --- title: atomWithRefreshAndDefault -nav: 8.06 +nav: 8.07 keywords: creators,refresh,default --- -## atomWithRefreshAndDefault - -> This is for an another implementation of [atomWithDefault](../utilities/resettable.mdx#atomwithdefault) +> This is for another implementation of [atomWithDefault](../utilities/resettable.mdx#atomwithdefault) ### Look back to atomWithDefault behavior diff --git a/docs/recipes/atom-with-refresh.mdx b/docs/recipes/atom-with-refresh.mdx new file mode 100644 index 0000000000..c709484c71 --- /dev/null +++ b/docs/recipes/atom-with-refresh.mdx @@ -0,0 +1,62 @@ +--- +title: atomWithRefresh +nav: 8.06 +keywords: creators,refresh +--- + +> `atomWithRefresh` creates a derived atom that can be force-refreshed, by using +> the update function. + +This is helpful when you need to refresh asynchronous data after performing a +side effect. + +It can also be used to implement "pull to refresh" functionality. + +```ts +import { atom, Getter } from 'jotai' + +export function atomWithRefresh(fn: (get: Getter) => T) { + const refreshCounter = atom(0) + + return atom( + (get) => { + get(refreshCounter) + return fn(get) + }, + (_, set) => set(refreshCounter, (i) => i + 1) + ) +} +``` + +Here's how you'd use it to implement an refresh-able source of data: + +```js +import { atomWithRefresh } from 'XXX' + +const postsAtom = atomWithRefresh((get) => + fetch('https://jsonplaceholder.typicode.com/posts').then((r) => r.json()) +) +``` + +In a component: + +```jsx +const PostsList = () => { + const [posts, refreshPosts] = useAtom(postsAtom) + + return ( +
+ + + {/* Clicking this button will re-fetch the posts */} + +
+ ) +} +``` diff --git a/docs/recipes/atom-with-storage.mdx b/docs/recipes/atom-with-toggle-and-storage.mdx similarity index 94% rename from docs/recipes/atom-with-storage.mdx rename to docs/recipes/atom-with-toggle-and-storage.mdx index eccf0bb6f5..d4c5b894be 100644 --- a/docs/recipes/atom-with-storage.mdx +++ b/docs/recipes/atom-with-toggle-and-storage.mdx @@ -1,11 +1,9 @@ --- title: atomWithToggleAndStorage nav: 8.04 -keywords: creators,storage,toggle +keywords: creators,storage --- -## atomWithToggleAndStorage - > `atomWithToggleAndStorage` is like `atomWithToggle` but also persist the state anytime it changes in given storage using [`atomWithStorage`](../utilities/storage.mdx). Here is the source: diff --git a/docs/recipes/atom-with-toggle.mdx b/docs/recipes/atom-with-toggle.mdx index 6d2cdf6a78..410aa8e0e4 100644 --- a/docs/recipes/atom-with-toggle.mdx +++ b/docs/recipes/atom-with-toggle.mdx @@ -4,8 +4,6 @@ nav: 8.03 keywords: creators,toggle --- -## atomWithToggle - > `atomWithToggle` creates a new atom with a boolean as initial state & a setter function to toggle it. This avoids the boilerplate of having to set up another atom just to update the state of the first.