Skip to main content

injectAtomInstance

import { injectAtomInstance } from '@zedux/react'

An injector that accepts an atom template and its params and registers a static graph dependency on the resolved atom instance. Returns the resolved atom instance object.

Since the dependency is static, the atom instance that uses this injector will not reevaluate when the resolved atom instance's state changes. However, it will reevaluate when the atom instance's promise changes or when the atom instance is destroyed.

You can also pass an atom instance directly to register a static graph dependency on instances received from other sources, e.g. an atom instance param.

Examples​

Live Sandbox
123456789101112131415161718192021222324252627282930313233
const shouldCountAtom = atom('shouldCount', true)

const secondsAtom = atom('seconds', () => {
const shouldCountInstance = injectAtomInstance(shouldCountAtom)
const store = injectStore(0)

injectEffect(() => {
const intervalId = setInterval(() => {
const shouldCount = shouldCountInstance.getState()
if (!shouldCount) return

store.setState(val => val + 1)
}, 1000)

return () => clearInterval(intervalId)
}, [shouldCountInstance]) // instances are technically unstable references

return store
})

function Seconds() {
const [shouldCount, setShouldCount] = useAtomState(shouldCountAtom)
const state = useAtomValue(secondsAtom)

return (
<>
<div>Seconds: {state}</div>
<button onClick={() => setShouldCount(val => !val)}>
{shouldCount ? 'Pause' : 'Resume'} Counter
</button>
</>
)
}

Miscellaneous:

const instance = injectAtomInstance(myAtom)
const withParams = injectAtomInstance(myAtom, ['param 1', 'param 2'])

// passing an operation helps with debugging:
const injectCustomStuff = () => {
  const instance = injectAtomInstance(myAtom, [], 'injectCustomStuff')
}

Signature​

injectAtomInstance = (atom, params?, operation?) => instance
atom

Required. An atom template or atom instance.

If an atom template is passed, you must also pass any required params of the atom.

If an atom instance is passed, the params are ignored. In this case, injectAtomInstance() returns the passed instance as-is.

In all cases, injectAtomInstance() registers a static dependency on the resolved instance.

params

Required if the passed atom template takes required params. Optional if not.

Don't pass this or pass an empty array if the atom does not take params or if passing an atom instance.

config

Optional. An object containing the following optional properties:

{ operation, subscribe }
operation

A string. Default 'injectAtomInstance'.

You usually won't need to worry about this. But passing an operation string can help with debugging e.g. if the instance throws an error.

subscribe

A boolean. Default false.

Whether to subscribe to state updates in the resolved atom instance, triggering a reevaluation of the current atom instance every time the resolved atom instance's state changes.

injectAtomInstance() is "static" by default, meaning it won't subscribe to updates.

const val = injectAtomInstance(
  myAtom,
  [],
  { subscribe: true }
).getState()

// the above is equivalent to:
const val = injectAtomValue(myAtom)
Returns

The resolved atom instance.

Uses the passed atom template + params combo to find an existing atom instance. If no instance is found, creates one using the template and params and returns it.

See Also​