123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450
---title: Atom creatorsnav: 5.02---
## 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.
```tsimport { WritableAtom, atom } from 'jotai'
export function atomWithToggle(  initialValue?: boolean): WritableAtom<boolean, boolean | undefined> {  const anAtom = atom(initialValue, (get, set, nextValue?: boolean) => {    const update = nextValue ?? !get(anAtom)    set(anAtom, update)  })  return anAtom as WritableAtom<boolean, boolean | undefined>}```
An optional initial state can be provided as the first argument.
The setter function can have an optional argument to force a particular state, such as if you want to make a setActive function out of it.
Here is how it's used.
```jsimport { atomWithToggle } from 'XXX'
// will have an initial value set to trueconst isActiveAtom = atomWithToggle(true)```
And in a component:
```jsxconst Toggle = () => {  const [isActive, toggle] = useAtom(isActiveAtom)  return (    <>      <button onClick={() => toggle()}>        isActive: {isActive ? 'yes' : 'no'}      </button>      <button onClick={() => toggle(true)}>force true</button>      <button onClick={() => toggle(false)}>force false</button>    </>  )}```
## atomWithToggleAndStorage
> `atomWithToggleAndStorage` is like [`atomWithToggle`](#atom-with-toggle) but also persist the state anytime it changes in given storage using [`atomWithStorage`](../api/utils.mdx#atom-with-storage).Here is the source:
```tsimport { WritableAtom, atom } from 'jotai'import { atomWithStorage } from 'jotai/utils'
export function atomWithToggleAndStorage(  key: string,  initialValue?: boolean,  storage?: any): WritableAtom<boolean, boolean | undefined> {  const anAtom = atomWithStorage(key, initialValue, storage)  const derivedAtom = atom(    (get) => get(anAtom),    (get, set, nextValue?: boolean) => {      const update = nextValue ?? !get(anAtom)      set(anAtom, update)    }  )  return derivedAtom}```
And how it's used:
```jsimport { atomWithToggleAndStorage } from 'XXX'
// will have an initial value set to false & get stored in localStorage under the key "isActive"const isActiveAtom = atomWithToggleAndStorage('isActive')```
The usage in a component is also the same as [`atomWithToggle`](#atom-with-toggle).
## 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.
Note: Jotai uses `Object.is` internally to compare values when changes occur. If `areEqual(a, b)` returns false, but `Object.is(a, b)` returns true, Jotai will not trigger an update.
```tsimport { atomWithReducer } from 'jotai/utils'
export function atomWithCompare<Value>(  initialValue: Value,  areEqual: (prev: Value, next: Value) => boolean) {  return atomWithReducer(initialValue, (prev: Value, next: Value) => {    if (areEqual(prev, next)) {      return prev    }    return next  })}```
Here's how you'd use it to make an atom that ignores updates that are shallow-equal:
```tsimport { atomWithCompare } from 'XXX'import { shallowEquals } from 'YYY'import { CSSProperties } from 'react'
const styleAtom = atomWithCompare<CSSProperties>(  { backgroundColor: 'blue' },  shallowEquals)```
In a component:
```jsxconst StylePreview = () => {  const [styles, setStyles] = useAtom(styleAtom)  return (    <div>      <div styles={styles}>Style preview</div>      {/* Clicking this button twice will only trigger one render */}      <button onClick={() => setStyles({ ...styles, backgroundColor: 'red' })}>        Set background to red      </button>      {/* Clicking this button twice will only trigger one render */}      <button onClick={() => setStyles({ ...styles, fontSize: 32 })}>        Enlarge font      </button>    </div>  )}```
## atomWithRefresh
> `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 aside effect.
It can also be used to implement "pull to refresh" functionality.
```tsimport { atom, Getter } from 'jotai'
export function atomWithRefresh<T>(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:
```jsimport { atomWithRefresh } from 'XXX'
const postsAtom = atomWithRefresh((get) =>  fetch('https://jsonplaceholder.typicode.com/posts').then((r) => r.json()))```
In a component:
```jsxconst PostsList = () => {  const [posts, refreshPosts] = useAtom(postsAtom)  return (    <div>      <ul>        {posts.map((post) => (          <li key={post.id}>{post.title}</li>        ))}      </ul>      {/* Clicking this button will re-fetch the posts */}      <button type="button" onClick={refreshPosts}>        Refresh posts      </button>    </div>  )}```
## 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> returns a function to remove the listener.This can be useful when you want to create a component that can listen to whenan atom's state changes without having to re-render that component with each ofthose state changes.
```tsimport { useEffect } from 'react'import { atom, Getter, Setter, SetStateAction } from 'jotai'import { useUpdateAtom } from 'jotai/utils'
type Callback<Value> = (  get: Getter,  set: Setter,  newVal: Value,  prevVal: Value) => void
export function atomWithListeners<Value>(initialValue: Value) {  const baseAtom = atom(initialValue)  const listenersAtom = atom(<Callback<Value>[]>[])  const anAtom = atom(    (get) => get(baseAtom),    (get, set, arg: SetStateAction<Value>) => {      const prevVal = get(baseAtom)      set(baseAtom, arg)      const newVal = get(baseAtom)      get(listenersAtom).forEach((callback) => {        callback(get, set, newVal, prevVal)      })    }  )  const useListener = (callback: Callback<Value>) => {    const setListeners = useUpdateAtom(listenersAtom)    useEffect(() => {      setListeners((prev) => [...prev, callback])      return () =>        setListeners((prev) => {          const index = prev.indexOf(callback)          return [...prev.slice(0, index), ...prev.slice(index + 1)]        })    }, [setListeners, callback])  }  return [anAtom, useListener] as const}```
In a component:
```jsxconst [countAtom, useCountListener] = atomWithListeners(0)
function EvenCounter() {  const [evenCount, setEvenCount] = useState(0)  useCountListener(    useCallback(      (get, set, newVal, prevVal) => {        // Every time `countAtom`'s value is set, we check if its new value        // is even, and if it is, we increment `evenCount`.        if (newVal % 2 === 0) {          setEvenCount((c) => c + 1)        }      },      [setEvenCount]    )  )  return <>Count was set to an even number {evenCount} times.</>}```
## atomWithBroadcast
> `atomWithBroadcast` creates an atom. The atom will be shared between> browser tabs and frames, similar to `atomWithStorage` but with the> initialization limitation.This can be useful when you want the state to interact with each other withoutthe use of localStorage and that by just using The Broadcast Channel API allowsbasic communication between browsing contexts (that is, windows, tabs, frames,create a component or iframes) and workers on the same origin. According to the MDN documentation receiving a message in initialization is not supported in broadcast and if we want to support that we may need to add extra stuff to atomWithBroadcast (like local storage).
```tsximport { atom } from 'jotai'
export function atomWithBroadcast<Value>(key: string, initialValue: Value) {  const baseAtom = atom(initialValue)  const listeners = new Set<(event: MessageEvent<any>) => void>()  const channel = new BroadcastChannel(key)  channel.onmessage = (event) => {    listeners.forEach((l) => l(event))  }  const broadcastAtom = atom<Value, { isEvent: boolean; value: Value }>(    (get) => get(baseAtom),    (get, set, update) => {      set(baseAtom, update.value)      if (!update.isEvent) {        channel.postMessage(get(baseAtom))      }    }  )  broadcastAtom.onMount = (setAtom) => {    const listener = (event: MessageEvent<any>) => {      setAtom({ isEvent: true, value: event.data })    }    listeners.add(listener)    return () => {      listeners.delete(listener)    }  }  const returnedAtom = atom<Value, Value>(    (get) => get(broadcastAtom),    (get, set, update) => {      set(broadcastAtom, { isEvent: false, value: update })    }  )  return returnedAtom}const broadAtom = atomWithBroadcast('count', 0)
const ListOfThings = () => {  const [count, setCount] = useAtom(broadAtom)  return (    <div>      {count}      <button onClick={() => setCount(count + 1)}>+1</button>    </div>  )}```
<CodeSandbox id="ugkzm0" />## 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.
```tsximport { atom, SetStateAction } from 'jotai'
export default function atomWithDebounce<T>(  initialValue: T,  delayMilliseconds = 500,  shouldDebounceOnReset = false) {  const prevTimeoutAtom = atom<ReturnType<typeof setTimeout> | undefined>(    undefined  )  // DO NOT EXPORT currentValueAtom as using this atom to set state can cause  // inconsistent state between currentValueAtom and debouncedValueAtom  const _currentValueAtom = atom(initialValue)  const isDebouncingAtom = atom(false)  const debouncedValueAtom = atom(    initialValue,    (get, set, update: SetStateAction<T>) => {      clearTimeout(get(prevTimeoutAtom))      const prevValue = get(_currentValueAtom)      const nextValue =        typeof update === 'function'          ? (update as (prev: T) => T)(prevValue)          : update      const onDebounceStart = () => {        set(_currentValueAtom, nextValue)        set(isDebouncingAtom, true)      }      const onDebounceEnd = () => {        set(debouncedValueAtom, nextValue)        set(isDebouncingAtom, false)      }      onDebounceStart()      if (!shouldDebounceOnReset && nextValue === initialValue) {        onDebounceEnd()        return      }      const nextTimeoutId = setTimeout(() => {        onDebounceEnd()      }, delayMilliseconds)      // set previous timeout atom in case it needs to get cleared      set(prevTimeoutAtom, nextTimeoutId)    }  )  // exported atom setter to clear timeout if needed  const clearTimeoutAtom = atom(null, (get, set, _arg) => {    clearTimeout(get(prevTimeoutAtom))    set(isDebouncingAtom, false)  })  return {    currentValueAtom: atom((get) => get(_currentValueAtom)),    isDebouncingAtom,    clearTimeoutAtom,    debouncedValueAtom,  }}```
### Caveat
Please note that this atom has different objectives from concurrent features in React 18 such as `useTransition` and `useDeferredValue` whose main aim is to prevent blocking of interaction with the page for expensive updates.
For more info, please read this github discussion https://github.com/reactwg/react-18/discussions/41 under the section titled **"How is it different from setTimeout?"**
### Example Usage
The sandbox link below shows how we would use a derived atom to fetch state based on the value of `debouncedValueAtom`.
When typing a pokemon's name in `<SearchInput>`, we do not send a get request on every letter, but only after `delayMilliseconds` has passed since the last text input.
This reduces the number of backend requests to the server.
<CodeSandbox id="cjrz2y" />