Functions marked with {馃殌} are considered advanced, and should typically not be needed.Consider downloading our handy cheat sheet that explains all important APIs on a single page: These are the most important MobX APIs. Understanding observable, computed, reaction and action is enough to master and use MobX in your applications! Making things observable. Usage: Properties, entire objects, arrays, Maps and Sets can all be made observable. Usage: Automatically make properties, objects, arrays, Maps and Sets observable. {馃殌} Usage: Can be used to introduce new properties on the Old-fashioned constructor functions can nicely leverage It is possible to use Usage: Clones an object and makes it observable. Source can be a plain object, array, Map or Set. By default, {馃殌} Usage: Alias for {馃殌} Usage: Creates a new observable array based on the provided If the values in the array should not be turned into observables automatically, use the {馃殌} Usage: Creates a new observable ES6 Map based on the provided Besides all the language built-in Map functions, the following goodies are available on observable Maps as well: If the values in the Map should not be turned into observables automatically, use the {馃殌} Usage: Creates a new observable ES6 Set based on the provided If the values in the Set should not be turned into observables automatically, use the Unlike Map keys, Set values are not tracked individually. Usage: Like the Usage: Like the {馃殌} Usage: Like the {馃殌} Usage: Alias for the observable annotation.Core APIs
Creating observables
makeObservable
makeObservable(target, annotations?, options?)
(further information)makeAutoObservable
makeAutoObservable(target, overrides?, options?)
(further information)extendObservable
extendObservable(target, properties, overrides?, options?)
target
object and make them observable immediately. Basically a shorthand for Object.assign(target, properties); makeAutoObservable(target, overrides, options);
. However, existing properties on target
won't be touched.extendObservable
:function Person(firstName, lastName) { extendObservable(this, { firstName, lastName })}const person = new Person("Michel", "Weststrate")
extendObservable
to add observable fields to an existing object after instantiation, but be careful that adding an observable property this way is in itself not a fact that can be observed.observable
observable(source, overrides?, options?)
, observable
(annotation) or @observable accessor
(field decorator).(further information)observable
is applied recursively. If one of the encountered values is an object or array, that value will be passed through observable
as well.observable.object
observable.object(source, overrides?, options?)
(further information)observable(source, overrides?, options?)
. Creates a clone of the provided object and makes all of its properties observable.observable.array
observable.array(initialValues?, options?)
initialValues
.To convert observable arrays back to plain arrays, use the .slice()
method, or check out toJS to convert them recursively.Besides all the language built-in array functions, the following goodies are available on observable arrays as well:clear()
removes all current entries from the array.replace(newItems)
replaces all existing entries in the array with new ones.remove(value)
removes a single item by value from the array and returns true
if the item was found and removed.{ deep: false }
option to make the array shallowly observable.observable.map
observable.map(initialMap?, options?)
initialMap
.They are very useful if you don't want to react just to the change of a specific entry, but also to their addition and removal.Creating observable Maps is the recommended approach for creating dynamically keyed collections if you don't have enabled Proxies.toJSON()
returns a shallow plain object representation of this Map (use toJS for a deep copy).merge(values)
copies all entries from the provided values
(plain object, array of entries or a string-keyed ES6 Map) into this Map.replace(values)
replaces the entire contents of this Map with the provided values
.{ deep: false }
option to make the Map shallowly observable.observable.set
observable.set(initialSet?, options?)
initialSet
. Use it whenever you want to create a dynamic set where the addition and removal of values needs to be observed, but where values can appear only once in the entire collection.{ deep: false }
option to make the Set shallowly observable.observable.ref
observable.ref
(annotation)(further information)observable
annotation, but only reassignments will be tracked. The assigned values themselves won't be made observable automatically. For example, use this if you intend to store immutable data in an observable field.observable.shallow
observable.shallow
(annotation)(further information)observable.ref
annotation, but for collections. Any collection assigned will be made observable, but the contents of the collection itself won't become observable.observable.struct
observable.struct
(annotation)(further information)observable
annotation, except that any assigned value that is structurally equal to the current value will be ignored.observable.deep
observable.deep
(annotation)(further information)
observable.box
{馃殌} Usage: observable.box(value, options?)
All primitive values in JavaScript are immutable and hence per definition not observable.Usually that is fine, as MobX can just make the property that contains the value observable.In rare cases, it can be convenient to have an observable primitive that is not owned by an object.For such cases, it is possible to create an observable box that manages such a primitive.
observable.box(value)
accepts any value and stores it inside a box. The current value can be accessed through .get()
and updated using .set(newValue)
.
import { observable, autorun } from "mobx"const cityName = observable.box("Vienna")autorun(() => { console.log(cityName.get())})// Prints: 'Vienna'cityName.set("Amsterdam")// Prints: 'Amsterdam'
If the values in the box should not be turned into observables automatically, use the { deep: false }
option to make the box shallowly observable.
Actions
An action is any piece of code that modifies the state.
action
Usage: action(fn)
, action
(annotation) or @action
(method / field decorator)(further information)
Use on functions that intend to modify the state.
runInAction
{馃殌} Usage: runInAction(fn)
(further information)
Create a one-time action that is immediately invoked.
flow
Usage: flow(fn)
, flow
(annotation) or @flow
(generator method decorator)(further information)
MobX friendly replacement for async
/ await
that supports cancellation.
flowResult
Usage: flowResult(flowFunctionResult)
(further information)
For TypeScript users only. Utility that casts the output of the generator to a promise.This is just a type-wise correction for the promise wrapping done by flow
. At runtime it directly returns the inputted value.
Computeds
Computed values can be used to derive information from other observables.
computed
Usage: computed(fn, options?)
, computed(options?)
(annotation) or @computed
(getter decorator)(further information)
Creates an observable value that is derived from other observables, but won't be recomputed unless one of the underlying observables changes.
React integration
From the mobx-react
/ mobx-react-lite
packages.
observer
Usage: observer(component)
(further information)
A higher order component you can use to make a functional or class based React component re-render when observables change.
Observer
Usage: <Observer>{() => rendering}</Observer>
(further information)
Renders the given render function, and automatically re-renders it once one of the observables used in the render function changes.
useLocalObservable
Usage: useLocalObservable(() => source, annotations?)
(further information)
Creates a new observable object using makeObservable
, and keeps it around in the component for the entire life-cycle of the component.
Reactions
The goal of reactions is to model side effects that happen automatically.
autorun
Usage: autorun(() => effect, options?)
(further information)
Reruns a function every time anything it observes changes.
reaction
Usage: reaction(() => data, data => effect, options?)
(further information)
Reruns a side effect when any selected data changes.
when
Usage: when(() => condition, () => effect, options?)
or await when(() => condition, options?)
(further information)
Executes a side effect once when a observable condition becomes true.
Utilities
Utilities that might make working with observable objects or computed values more convenient. Less trivial utilities can also be found in the mobx-utils package.
onReactionError
{馃殌} Usage: onReactionError(handler: (error: any, derivation) => void)
Attaches a global error listener, which is invoked for every error that is thrown from a reaction. This can be used for monitoring or test purposes.
intercept
{馃殌} Usage: intercept(propertyName|array|object|Set|Map, listener)
(further information)
Intercepts changes before they are applied to an observable API. Returns a disposer function that stops the interception.
observe
{馃殌} Usage: observe(propertyName|array|object|Set|Map, listener)
(further information)
Low-level API that can be used to observe a single observable value. Returns a disposer function that stops the interception.
onBecomeObserved
{馃殌} Usage: onBecomeObserved(observable, property?, listener: () => void)
(further information)
Hook for when something becomes observed.
onBecomeUnobserved
{馃殌} Usage: onBecomeUnobserved(observable, property?, listener: () => void)
(further information)
Hook for when something stops being observed.
toJS
Usage: toJS(value)
(further information)
Recursively converts an observable object to a JavaScript object. Supports observable arrays, objects, Maps and primitives.
It does NOT recurse into non-observables, these are left as they are, even if they contain observables.Computed and other non-enumerable properties are completely ignored and won't be returned.
For more complex (de)serialization scenarios, it is recommended to give classes a (computed) toJSON
method, or use a serialization library like serializr.
const obj = mobx.observable({ x: 1})const clone = mobx.toJS(obj)console.log(mobx.isObservableObject(obj)) // trueconsole.log(mobx.isObservableObject(clone)) // false
Configuration
Fine-tuning your MobX instance.
configure
Usage: sets global behavior settings on the active MobX instance.(further information)Use it to change how MobX behaves as a whole.
Collection utilities {馃殌}
They enable manipulating observable arrays, objects and Maps with the same generic API. This can be useful in environments without Proxy support, but is otherwise typically not needed.
values
{馃殌} Usage: values(array|object|Set|Map)
(further information)
Returns all values in the collection as an array.
keys
{馃殌} Usage: keys(array|object|Set|Map)
(further information)
Returns all keys / indices in the collection as an array.
entries
{馃殌} Usage: entries(array|object|Set|Map)
(further information)
Returns a [key, value]
pair of every entry in the collection as an array.
set
{馃殌} Usage: set(array|object|Map, key, value)
(further information)
Updates the collection.
remove
{馃殌} Usage: remove(array|object|Map, key)
(further information)
Removes item from the collection.
has
{馃殌} Usage: has(array|object|Map, key)
(further information)
Checks for membership in the collection.
get
{馃殌} Usage: get(array|object|Map, key)
(further information)
Gets value from the collection with key.
Introspection utilities {馃殌}
Utilities that might come in handy if you want to inspect the internal state of MobX, or want to build cool tools on top of MobX.
isObservable
{馃殌} Usage: isObservable(array|object|Set|Map)
Is the object / collection made observable by MobX?
isObservableProp
{馃殌} Usage: isObservableProp(object, propertyName)
Is the property observable?
isObservableArray
{馃殌} Usage: isObservableArray(array)
Is the value an observable array?
isObservableObject
{馃殌} Usage: isObservableObject(object)
Is the value an observable object?
isObservableSet
{馃殌} Usage: isObservableSet(set)
Is the value an observable Set?
isObservableMap
{馃殌} Usage: isObservableMap(map)
Is the value an observable Map?
isBoxedObservable
{馃殌} Usage: isBoxedObservable(value)
Is the value an observable box, created using observable.box
?
isAction
{馃殌} Usage: isAction(func)
Is the function marked as an action
?
isComputed
{馃殌} Usage: isComputed(boxedComputed)
Is this a boxed computed value, created using computed(() => expr)
?
isComputedProp
{馃殌} Usage: isComputedProp(object, propertyName)
Is this a computed property?
trace
{馃殌} Usage: trace()
, trace(true)
(enter debugger) or trace(object, propertyName, enterDebugger?)
(further information)
Should be used inside an observer, reaction or computed value. Logs when the value is invalidated, or sets the debugger breakpoint if called with true.
spy
{馃殌} Usage: spy(eventListener)
(further information)
Registers a global spy listener that listens to all events that happen in MobX.
getDebugName
{馃殌} Usage: getDebugName(reaction|array|Set|Map)
or getDebugName(object|Map, propertyName)
(further information)
Returns the (generated) friendly debug name for an observable or reaction.
getDependencyTree
{馃殌} Usage: getDependencyTree(object, computedPropertyName)
(further information)
Returns a tree structure with all observables the given reaction / computation currently depends upon.
getObserverTree
{馃殌} Usage: getObserverTree(array|Set|Map)
or getObserverTree(object|Map, propertyName)
(further information)
Returns a tree structure with all reactions / computations that are observing the given observable.
Extending MobX {馃殌}
In the rare case you want to extend MobX itself.
createAtom
{馃殌} Usage: createAtom(name, onBecomeObserved?, onBecomeUnobserved?)
(further information)
Creates your own observable data structure and hooks it up to MobX. Used internally by all observable data types. Atom exposes two report methods to notify MobX with when:
reportObserved()
: the atom has become observed, and should be considered part of the dependency tree of the current derivation.reportChanged()
: the atom has changed, and all derivations depending on it should be invalidated.
getAtom
{馃殌} Usage: getAtom(thing, property?)
(further information)
Returns the backing atom.
transaction
{馃殌} Usage: transaction(worker: () => any)
Transaction is a low-level API. It is recommended to use action or runInAction instead.
Used to batch a bunch of updates without running any reactions until the end of the transaction. Like untracked, it is automatically applied by action
, so usually it makes more sense to use actions than to use transaction
directly.
It takes a single, parameterless worker
function as an argument, and returns any value that was returned by it.Note that transaction
runs completely synchronously and can be nested. Only after completing the outermost transaction
, the pending reactions will be run.
import { observable, transaction, autorun } from "mobx"const numbers = observable([])autorun(() => console.log(numbers.length, "numbers!"))// Prints: '0 numbers!'transaction(() => { transaction(() => { numbers.push(1) numbers.push(2) }) numbers.push(3)})// Prints: '3 numbers!'
untracked
{馃殌} Usage: untracked(worker: () => any)
Untracked is a low-level API. It is recommended to use reaction, action or runInAction instead.
Runs a piece of code without establishing observers. Like transaction
, untracked
is automatically applied by action
, so usually it makes more sense to use actions than to use untracked
directly.
const person = observable({ firstName: "Michel", lastName: "Weststrate"})autorun(() => { console.log( person.lastName, ",", // This untracked block will return the person's // firstName without establishing a dependency. untracked(() => person.firstName) )})// Prints: 'Weststrate, Michel'person.firstName = "G.K."// Doesn't print!person.lastName = "Chesterton"// Prints: 'Chesterton, G.K.'