## Sponsors
Become a sponsor and get your logo on our README on Github with a link to your site. [[Become a sponsor](https://opencollective.com/mobx#sponsor)]
---
---
title: Analyzing reactivity
hide_title: true
---
# This document has been updated and moved
[Please click on this link to open the updated version.](../analyzing-reactivity.md)
---
---
title: Enabling decorators
hide_title: true
---
# This document has been updated and moved
[Please click on this link to open the updated version.](../enabling-decorators.md)
---
---
title: Defining data stores
hide_title: true
---
# This document has been updated and moved
[Please click on this link to open the updated version.](../defining-data-stores.md)
---
---
title: Understanding reactivity
hide_title: true
---
# This document has been updated and moved
[Please click on this link to open the updated version.](../understanding-reactivity.md)
---
---
title: Collection utilities
sidebar_label: Collection utilities {🚀}
hide_title: true
---
# Collection utilities {🚀}
They enable manipulating observable arrays, objects and Maps with the same generic API.
These APIs are fully reactive, which means that even [without `Proxy` support](configuration.md#limitations-without-proxy-support) new property declarations can be detected by MobX if `set` is used to add them, and `values` or `keys` are used to iterate over them.
Another benefit of `values`, `keys` and `entries` is that they return arrays rather than iterators, which makes it possible to, for example, immediately call `.map(fn)` on the results.
All that being said, a typical project has little reason to use these APIs.
Access:
- `values(collection)` returns an array of all the values in the collection.
- `keys(collection)` returns an array of all the keys in the collection.
- `entries(collection)` returns an array of all the entries `[key, value]` pairs in the collection.
Mutation:
- `set(collection, key, value)` or `set(collection, { key: value })` update the given collection with the provided key / value pair(s).
- `remove(collection, key)` removes the specified child from the collection. Splicing is used for arrays.
- `has(collection, key)` returns _true_ if the collection has the specified _observable_ property.
- `get(collection, key)` returns the child under the specified key.
If you use the access APIs in an environment without `Proxy` support, then also use the mutation APIs so they can detect the changes.
```javascript
import { autorun, get, set, observable, values } from "mobx"
const twitterUrls = observable.object({
Joe: "twitter.com/joey"
})
autorun(() => {
// Get can track not yet existing properties.
console.log(get(twitterUrls, "Sara"))
})
autorun(() => {
console.log("All urls: " + values(twitterUrls).join(", "))
})
set(twitterUrls, { Sara: "twitter.com/horsejs" })
```
---
---
title: Computeds with arguments
sidebar_label: Computeds with arguments {🚀}
hide_title: true
---
# Computeds with arguments {🚀}
The `computed` annotation can only be used on getters, which don't take arguments.
What about computations that do take arguments?
Take the below example of a React component that renders a specific `Item`,
and the application supports multi-selection.
How can we implement a derivation like `store.isSelected(item.id)`?
```javascript
import * as React from 'react'
import { observer } from 'mobx-react-lite'
const Item = observer(({ item, store }) => (
{item.title}
))
```
There are four ways in which we can approach this. You can try the solutions below in [this CodeSandbox](https://codesandbox.io/s/multi-selection-odup1?file=/src/index.tsx).
## 1. Derivations don't _need_ to be `computed`
A function doesn't need to be marked as `computed` in order for MobX to track it.
The above example would already work completely fine out of the box.
It is important to realize that computed values are only _caching points_.
If the derivations are pure (and they should be), having a getter or function without `computed` doesn't change the behavior, it is just slightly less efficient.
The above example works fine despite `isSelected` not being a `computed`. The `observer` component will detect and subscribe to any observables that were read by `isSelected` because the function executes as part of rendering that is tracked.
It is good to realize that all `Item` components, in this case, will respond to future selection changes,
as they all subscribe directly to the observables that capture the selection.
This is a worst-case example. In general, it is completely fine to have unmarked functions that derive information, and this is a good default strategy until numbers prove anything else should be done.
## 2. Close over the arguments
This is a more efficient implementation compared to the original.
```javascript
import * as React from 'react'
import { computed } from 'mobx'
import { observer } from 'mobx-react-lite'
const Item = observer(({ item, store }) => {
const isSelected = computed(() => store.isSelected(item.id)).get()
return (
{item.title}
)
})
```
We create a fresh computed value in the middle of a reaction. This works fine and does introduce that additional caching point, avoiding all components having to directly respond to every selection change.
The advantage of this approach is that the component itself will only re-render if the
`isSelected` state toggles, in which case we indeed have to re-render to swap the `className`.
The fact that we create a new `computed` in a next render is fine, this one will now become the caching
point and the previous one will be cleaned up nicely.
This is a great and advanced optimization technique.
## 3. Move the state
In this specific case the selection could also be stored as an `isSelected` observable on the `Item`. The selection in the store could then be expressed as a `computed` rather than an observable: `get selection() { return this.items.filter(item => item.isSelected) }`, and we don't need `isSelected` anymore.
## 4. Use computedFn {🚀}
Finally,
[`computedFn`](https://github.com/mobxjs/mobx-utils#computedfn) from `mobx-utils` can be used in the definition of `todoStore.selected` to automatically memoize `isSelected`.
It creates a function that memoizes the output for every combination of input arguments.
We recommend to not resort to this one too quickly. It is typical for memoization, that you will need to think about how many different arguments the function is going to be called with, before you can reason about the memory consumption.
It does however automatically clean up entries if their results aren't observed by any reaction, so it won't leak memory in normal circumstances.
Again, check out the [linked CodeSandbox](https://codesandbox.io/s/multi-selection-odup1?file=/src/index.tsx) to try this one out.
---
---
title: Deriving information with computeds
sidebar_label: Computeds
hide_title: true
---
# Deriving information with computeds
Usage:
- `computed` _(annotation)_
- `computed(options)` _(annotation)_
- `computed(fn, options?)`
- `@computed` _(getter decorator)_
- `@computed(options)` _(getter decorator)_
Computed values can be used to derive information from other observables.
They evaluate lazily, caching their output and only recomputing if one of the underlying observables has changed.
If they are not observed by anything, they suspend entirely.
Conceptually, they are very similar to formulas in spreadsheets, and can't be underestimated. They help in reducing the amount of state you have to store and are highly optimized. Use them wherever possible.
## Example
Computed values can be created by annotating JavaScript [getters](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) with `computed`.
Use `makeObservable` to declare a getter as computed. If you instead want all getters to be automatically declared as `computed`, you can use either `makeAutoObservable`, `observable` or `extendObservable`. Computed getters become non-enumerable.
To help illustrate the point of computed values, the example below relies on [`autorun`](reactions.md#autorun) from the [Reactions {🚀}](reactions.md) advanced section.
```javascript
import { makeObservable, observable, computed, autorun } from "mobx"
class OrderLine {
price = 0
amount = 1
constructor(price) {
makeObservable(this, {
price: observable,
amount: observable,
total: computed
})
this.price = price
}
get total() {
console.log("Computing...")
return this.price * this.amount
}
}
const order = new OrderLine(0)
const stop = autorun(() => {
console.log("Total: " + order.total)
})
// Computing...
// Total: 0
console.log(order.total)
// (No recomputing!)
// 0
order.amount = 5
// Computing...
// (No autorun)
order.price = 2
// Computing...
// Total: 10
stop()
order.price = 3
// Neither the computation nor autorun will be recomputed.
```
The above example nicely demonstrates the benefits of a `computed` value, it acts as a caching point.
Even though we change the `amount`, and this will trigger the `total` to recompute,
it won't trigger the `autorun`, as `total` will detect its output hasn't been affected, so there is no need to update the `autorun`.
In comparison, if `total` would not be annotated, the `autorun` would run its effect 3 times,
as it would directly depend on `total` and `amount`. [Try it out yourself](https://codesandbox.io/s/computed-3cjo9?file=/src/index.tsx).
This is the dependency graph that would be created for the above example.
## Rules
When using computed values there are a couple of best practices to follow:
1. They should not have side effects or update other observables.
2. Avoid creating and returning new observables.
3. They should not depend on non-observable values.
## Tips
**Tip:** computed values will be suspended if they are _not_ observed
It sometimes confuses people new to MobX, perhaps used to a library like [Reselect](https://github.com/reduxjs/reselect), that if you create a computed property but don't use it anywhere in a reaction, it is not memoized and appears to be recomputed more often than necessary. For example, if we extended the above example with calling `console.log(order.total)` twice, after we called `stop()`, the value would be recomputed twice. This allows MobX to automatically suspend computations that are not actively in use to avoid unnecessary updates to computed values that are not being accessed. But if a computed property is _not_ in use by some reaction, then computed expressions are evaluated each time their value is requested, so they behave just like a normal property. If you only fiddle around computed properties might not seem efficient, but when applied in a project that uses `observer`, `autorun`, etc., they become very efficient. The following code demonstrates the issue: ```javascript // OrderLine has a computed property `total`. const line = new OrderLine(2.0) // If you access `line.total` outside of a reaction, it is recomputed every time. setInterval(() => { console.log(line.total) }, 60) ``` It can be overridden by setting the annotation with the `keepAlive` option ([try it out yourself](https://codesandbox.io/s/computed-3cjo9?file=/src/index.tsx)) or by creating a no-op `autorun(() => { someObject.someComputed })`, which can be nicely cleaned up later if needed. Note that both solutions have the risk of creating memory leaks. Changing the default behavior here is an anti-pattern. MobX can also be configured with the [`computedRequiresReaction`](configuration.md#computedrequiresreaction-boolean) option, to report an error when computeds are accessed outside of a reactive context.**Tip:** computed values can have setters
It is possible to define a [setter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/set) for computed values as well. Note that these setters cannot be used to alter the value of the computed property directly, but they can be used as an "inverse" of the derivation. Setters are automatically marked as actions. For example: ```javascript class Dimension { length = 2 constructor() { makeAutoObservable(this) } get squared() { return this.length * this.length } set squared(value) { this.length = Math.sqrt(value) } } ```{🚀} **Tip:** `computed.struct` for comparing output structurally
If the output of a computed value that is structurally equivalent to the previous computation doesn't need to notify observers, `computed.struct` can be used. It will make a structural comparison first, rather than a reference equality check, before notifying observers. For example: ```javascript class Box { width = 0 height = 0 constructor() { makeObservable(this, { width: observable, height: observable, topRight: computed.struct }) } get topRight() { return { x: this.width, y: this.height } } } ``` By default, the output of a `computed` is compared by reference. Since `topRight` in the above example will always produce a new result object, it is never going to be considered equal to a previous output. Unless `computed.struct` is used. However, in the above example _we actually don't need `computed.struct`_! Computed values normally only re-evaluate if the backing values change. That's why `topRight` will only react to changes in `width` or `height`. Since if any of those change, we would get a different `topRight` coordinate anyway. `computed.struct` would never have a cache hit and be a waste of effort, so we don't need it. In practice, `computed.struct` is less useful than it sounds. Only use it if changes in the underlying observables can still lead to the same output. For example, if we were rounding the coordinates first, the rounded coordinates might be equal to the previously rounded coordinates even though the underlying values aren't. Check out the [`equals`](#equals) option for further customizations on determining whether the output has changed.{🚀} **Tip:** computed values with arguments
Although getters don't take arguments, several strategies to work with derived values that need arguments are discussed [here](computeds-with-args.md).{🚀} **Tip:** create standalone computed values with `computed(expression)`
`computed` can also be invoked directly as a function, just like [`observable.box`](api.md#observablebox) creates a standalone computed value. Use `.get()` on the returned object to get the current value of the computation. This form of `computed` is not used very often, but in some cases where you need to pass a "boxed" computed value around it might prove itself useful, one such case is discussed [here](computeds-with-args.md).Using legacy decorators
We do not recommend codebases to use TypeScript / Babel legacy decorators since they well never become an official part of the language, but you can still use them. It does require a specific setup for transpilation: MobX before version 6 encouraged the use of legacy decorators and mark things as `observable`, `computed` and `action`. While MobX 6 recommends against using these decorators (and instead use either modern decorators or [`makeObservable` / `makeAutoObservable`](observable-state.md)), it is in the current major version still possible. Support for legacy decorators will be removed in MobX 7. ```javascript import { makeObservable, observable, computed, action } from "mobx" class Todo { id = Math.random() @observable title = "" @observable finished = false constructor() { makeObservable(this) } @action toggle() { this.finished = !this.finished } } class TodoList { @observable todos = [] @computed get unfinishedTodoCount() { return this.todos.filter(todo => !todo.finished).length } constructor() { makeObservable(this) } } ```Migrating from legacy decorators
To migrate from legacy decorators to modern decorators, perform the following steps: 1. Disable / remove the `experimentalDecorators` flag from your TypeScript configuration (or Babel equivalent) 2. Remove all `makeObservable(this)` calls from class constructors that use decorators. 3. Replace all instances of `@observable` (and variations) with `@observable accessor` Please note that adding `accessor` to a class property will change it into `get` and `set` class methods. Unlike class properties, class methods are not enumerable. This may introduce new behavior with some APIs, such as `Object.keys`, `JSON.stringify`, etc.Decorator changes / gotchas
MobX' 2022.3 Decorators are very similar to the MobX 5 decorators, so usage is mostly the same, but there are some gotchas: - `@observable accessor` decorators are _not_ enumerable. `accessor`s do not have a direct equivalent in the past - they're a new concept in the language. We've chosen to make them non-enumerable, non-own properties in order to better follow the spirit of the ES language and what `accessor` means. The main cases for enumerability seem to have been around serialization and rest destructuring. - Regarding serialization, implicitly serializing all properties probably isn't ideal in an OOP-world anyway, so this doesn't seem like a substantial issue (consider implementing `toJSON` or using `serializr` as possible alternatives) - Addressing rest-destructuring, such is an anti-pattern in MobX - doing so would (likely unwantedly) touch all observables and make the observer overly-reactive). - `@action some_field = () => {}` was and is valid usage. However, inheritance is different between legacy decorators and modern decorators. - In legacy decorators, if superclass has a field decorated by `@action`, and subclass tries to override the same field, it will throw a `TypeError: Cannot redefine property`. - In modern decorators, if superclass has a field decorated by `@action`, and subclass tries to override the same field, it's allowed to override the field. However, the field on subclass is not an action unless it's also decorated with `@action` in subclass declaration.**All non-observable** (stateless) fields (`action`, `flow`) are **non-writable**. When using modern decorators, there is no need to call `makeObservable`, below is what a decorator based class looks like. Note that the `@observable` annotation should always be used in combination with the `accessor` keyword. ```javascript import { observable, computed, action, flow } from "mobx" class Doubler { @observable accessor value constructor(value) { this.value = value } @computed get double() { return this.value * 2 } @action increment() { this.value++ } @flow *fetch() { const response = yield fetch("/api/value") this.value = response.json() } } ``` ```javascript import { makeAutoObservable } from "mobx" function createDoubler(value) { return makeAutoObservable({ value, get double() { return this.value * 2 }, increment() { this.value++ } }) } ``` Note that classes can leverage `makeAutoObservable` as well. The difference in the examples just demonstrate how MobX can be applied to different programming styles. ```javascript import { observable } from "mobx" const todosById = observable({ "TODO-123": { title: "find a decent task management system", done: false } }) todosById["TODO-456"] = { title: "close all tickets older than two weeks", done: true } const tags = observable(["high prio", "medium prio", "low prio"]) tags.push("prio: for fun") ``` In contrast to the first example with `makeObservable`, `observable` supports adding (and removing) _fields_ to an object. This makes `observable` great for collections like dynamically keyed objects, arrays, Maps and Sets. To use legacy decorators, `makeObservable(this)` should be called in the constructor to make sure decorators work. ```javascript import { observable, computed, action, flow } from "mobx" class Doubler { @observable value constructor(value) { makeObservable(this) this.value = value } @computed get double() { return this.value * 2 } @action increment() { this.value++ } @flow *fetch() { const response = yield fetch("/api/value") this.value = response.json() } } ``` ## `makeAutoObservable` Usage: - `makeAutoObservable(target, overrides?, options?)` `makeAutoObservable` is like `makeObservable` on steroids, as it infers all the properties by default. You can however use the `overrides` parameter to override the default behavior with specific annotations — in particular `false` can be used to exclude a property or method from being processed entirely. Check out the code above for an example. The `makeAutoObservable` function can be more compact and easier to maintain than using `makeObservable`, since new members don't have to be mentioned explicitly. However, `makeAutoObservable` cannot be used on classes that have super or are [subclassed](subclassing.md). Inference rules: - All _own_ properties become `observable`. - All `getters` become `computed`. - All `setters` become `action`. - All _functions_ become [`autoAction`](#autoAction). - All _generator_ functions become `flow`. (Note that generator functions are not detectable in some transpiler configurations, if flow doesn't work as expected, make sure to specify `flow` explicitly.) - Members marked with `false` in the `overrides` argument will not be annotated. For example, using it for read only fields such as identifiers. ## `observable` Usage: - `observable(source, overrides?, options?)` - `@observable accessor` _(field decorator)_ The `observable` annotation can also be called as a function to make an entire object observable at once. The `source` object will be cloned and all members will be made observable, similar to how it would be done by `makeAutoObservable`. Likewise, an `overrides` map can be provided to specify the annotations of specific members. Check out the above code block for an example. The object returned by `observable` will be a Proxy, which means that properties that are added later to the object will be picked up and made observable as well (except when [proxy usage](configuration.md#proxy-support) is disabled). The `observable` method can also be called with collections types like [arrays](api.md#observablearray), [Maps](api.md#observablemap) and [Sets](api.md#observableset). Those will be cloned as well and converted into their observable counterparts. > Tip: as holds for JavaScript in general, don't use observable plain objects to create a keyed collection (for example to store a mapping from a user's UUID to user object), use maps instead. Object descriptors are aggressively cached by MobX, so if property names are unstable, this might result in memory leaks.
**Example:** observable array
The following example creates an observable and observes it using [`autorun`](reactions.md#autorun). Working with Map and Set collections works similarly. ```javascript import { observable, autorun } from "mobx" const todos = observable([ { title: "Spoil tea", completed: true }, { title: "Make coffee", completed: false } ]) autorun(() => { console.log( "Remaining:", todos .filter(todo => !todo.completed) .map(todo => todo.title) .join(", ") ) }) // Prints: 'Remaining: Make coffee' todos[0].completed = false // Prints: 'Remaining: Spoil tea, Make coffee' todos[2] = { title: "Take a nap", completed: false } // Prints: 'Remaining: Spoil tea, Make coffee, Take a nap' todos.shift() // Prints: 'Remaining: Make coffee, Take a nap' ``` Observable arrays have some additional nifty utility functions: - `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. Returns `true` if the item was found and removed.**Note:** primitives and class instances are never converted to observables
Primitive values cannot be made observable by MobX since they are immutable in JavaScript (but they can be [boxed](api.md#observablebox)). Although there is typically no use for this mechanism outside libraries. Class instances will never be made observable automatically by passing them to `observable` or assigning them to an `observable` property. Making class members observable is considered the responsibility of the class constructor.{🚀} **Tip:** observable (proxied) versus makeObservable (unproxied)
The primary difference between `make(Auto)Observable` and `observable` is that the first one modifies the object you are passing in as first argument, while `observable` creates a _clone_ that is made observable. The second difference is that `observable` creates a [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) object, to be able to trap future property additions in case you use the object as a dynamic lookup map. If the object you want to make observable has a regular structure where all members are known up-front, we recommend to use `makeObservable` as non proxied objects are a little faster, and they are easier to inspect in the debugger and `console.log`. Because of that, `make(Auto)Observable` is the recommended API to use in factory functions. Note that it is possible to pass `{ proxy: false }` as an option to `observable` to get a non proxied clone.`observable.deep` | Defines a trackable field that stores state. If possible, any value assigned to `observable` is automatically converted to (deep) `observable`, [`autoAction`](#autoAction) or `flow` based on it's type. Only `plain object`, `array`, `Map`, `Set`, `function`, `generator function` are convertible. Class instances and others are untouched. | | `observable.ref` | Like `observable`, but only reassignments will be tracked. The assigned values are completely ignored and will NOT be automatically converted to `observable`/[`autoAction`](#autoAction)/`flow`. For example, use this if you intend to store immutable data in an observable field. | | `observable.shallow` | Like `observable.ref` but for collections. Any collection assigned will be made observable, but the contents of the collection itself won't become observable. | | `observable.struct` | Like `observable`, except that any assigned value that is structurally equal to the current value will be ignored. | | `action` | Mark a method as an action that will modify the state. Check out [actions](actions.md) for more details. Non-writable. | | `action.bound` | Like action, but will also bind the action to the instance so that `this` will always be set. Non-writable. | | `computed` | Can be used on a [getter](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Functions/get) to declare it as a derived value that can be cached. Check out [computeds](computeds.md) for more details. | | `computed.struct` | Like `computed`, except that if after recomputing the result is structurally equal to the previous result, no observers will be notified. | | `true` | Infer the best annotation. Check out [makeAutoObservable](#makeautoobservable) for more details. | | `false` | Explicitly do not annotate this property. | | `flow` | Creates a `flow` to manage asynchronous processes. Check out [flow](actions.md#using-flow-instead-of-async--await-) for more details. Note that the inferred return type in TypeScript might be off. Non-writable. | | `flow.bound` | Like flow, but will also bind the flow to the instance so that `this` will always be set. Non-writable. | | `override` | [Applicable to inherited `action`, `flow`, `computed`, `action.bound` overridden by subclass](subclassing.md). | | `autoAction` | Should not be used explicitly, but is used under the hood by `makeAutoObservable` to mark methods that can act as action or derivation, based on their calling context. It will be determined at runtime if the function is a derivation or action. | ## Limitations 1. `make(Auto)Observable` only supports properties that are already defined. Make sure your [**compiler configuration** is correct](installation.md#use-spec-compliant-transpilation-for-class-properties), or as work-around, that a value is assigned to all properties before using `make(Auto)Observable`. Without correct configuration, fields that are declared but not initialized (like in `class X { y; }`) will not be picked up correctly. 1. `makeObservable` can only annotate properties declared by its own class definition. If a sub- or superclass introduces observable fields, it will have to call `makeObservable` for those properties itself. 1. `options` argument can be provided only once. Passed `options` are _"sticky"_ and can NOT be changed later (eg. in [subclass](subclassing.md)). 1. **Every field can be annotated only once** (except for `override`). The field annotation or configuration can't change in [subclass](subclassing.md). 1. **All annotated** fields of non-plain objects (**classes**) are **non-configurable**.
[Can be disabled with `configure({ safeDescriptors: false })` {🚀☣️} ](configuration.md#safedescriptors-boolean). 1. **All non-observable** (stateless) fields (`action`, `flow`) are **non-writable**.
[Can be disabled with `configure({ safeDescriptors: false })` {🚀☣️} ](configuration.md#safedescriptors-boolean). 1. [Only **`action`, `computed`, `flow`, `action.bound`** defined **on prototype** can be **overridden** by subclass](subclassing.md). 1. By default _TypeScript_ will not allow you to annotate **private** fields. This can be overcome by explicitly passing the relevant private fields as generic argument, like this: `makeObservable
**Note:** options are *sticky* and can be provided only once
`options` argument can be provided only for `target` that is NOT observable yet.It is NOT possible to change options once the observable object was initialized.
Options are stored on target and respected by subsequent `makeObservable`/`extendObservable` calls.
You can't pass different options in [subclass](subclassing.md).
Server Side Rendering (SSR)
If `observer` is used in server side rendering context; make sure to call `enableStaticRendering(true)`, so that `observer` won't subscribe to any observables used, and no GC problems are introduced.**Note:** mobx-react vs. mobx-react-lite
In this documentation we used `mobx-react-lite` as default. [mobx-react](https://github.com/mobxjs/mobx-react/) is it's big brother, which uses `mobx-react-lite` under the hood. It offers a few more features which are typically not needed anymore in greenfield projects. The additional things offered by mobx-react: 1. Support for React class components. 1. `Provider` and `inject`. MobX's own React.createContext predecessor which is not needed anymore. 1. Observable specific `propTypes`. Note that `mobx-react` fully repackages and re-exports `mobx-react-lite`, including functional component support. If you use `mobx-react`, there is no need to add `mobx-react-lite` as a dependency or import from it anywhere.**Note:** `observer` or `React.memo`?
`observer` automatically applies `memo`, so `observer` components never need to be wrapped in `memo`. `memo` can be applied safely to observer components because mutations (deeply) inside the props will be picked up by `observer` anyway if relevant.**Tip:** `observer` for class based React components
As stated above, class based components are only supported through `mobx-react`, and not `mobx-react-lite`. Briefly, you can wrap class-based components in `observer` just like you can wrap function components: ```javascript import React from "React" const TimerView = observer( class TimerView extends React.Component { render() { const { timer } = this.props return Seconds passed: {timer.secondsPassed} } } ) ``` Check out [mobx-react docs](https://github.com/mobxjs/mobx/tree/main/packages/mobx-react#class-components) for more information.**Tip:** nice component names in React DevTools
[React DevTools](https://reactjs.org/blog/2019/08/15/new-react-devtools.html) uses the display name information of components to properly display the component hierarchy. If you use: ```javascript export const MyComponent = observer(props =>hi
)
```
then no display name will be visible in the DevTools.
The following approaches can be used to fix this:
- use `function` with a name instead of an arrow function. `mobx-react` infers component name from the function name:
```javascript
export const MyComponent = observer(function MyComponent(props) {
return hi
})
```
- Transpilers (like Babel or TypeScript) infer component name from the variable name:
```javascript
const _MyComponent = props => hi
export const MyComponent = observer(_MyComponent)
```
- Infer from the variable name again, using default export:
```javascript
const MyComponent = props => hi
export default observer(MyComponent)
```
- [**Broken**] Set `displayName` explicitly:
```javascript
export const MyComponent = observer(props => hi
)
MyComponent.displayName = "MyComponent"
```
This is broken in React 16 at the time of writing; mobx-react `observer` uses a React.memo and runs into this bug: https://github.com/facebook/react/issues/18026, but it will be fixed in React 17.
Now you can see component names:
{🚀} **Tip:** when combining `observer` with other higher-order-components, apply `observer` first
When `observer` needs to be combined with other decorators or higher-order-components, make sure that `observer` is the innermost (first applied) decorator; otherwise it might do nothing at all.{🚀} **Tip:** deriving computeds from props
In some cases the computed values of your local observables might depend on some of the props your component receives. However, the set of props that a React component receives is in itself not observable, so changes to the props won't be reflected in any computed values. You have to manually update local observable state in order to properly derive computed values from latest data. ```javascript import { observer, useLocalObservable } from "mobx-react-lite" import { useEffect } from "react" const TimerView = observer(({ offset = 0 }) => { const timer = useLocalObservable(() => ({ offset, // The initial offset value secondsPassed: 0, increaseTimer() { this.secondsPassed++ }, get offsetTime() { return this.secondsPassed - this.offset // Not 'offset' from 'props'! } })) useEffect(() => { // Sync the offset from 'props' into the observable 'timer' timer.offset = offset }, [offset]) // Effect to set up a timer, only for demo purposes. useEffect(() => { const handle = setInterval(timer.increaseTimer, 1000) return () => { clearInterval(handle) } }, []) return Seconds passed: {timer.offsetTime} }) ReactDOM.render({🚀} **Tip:** useEffect and observables
`useEffect` can be used to set up side effects that need to happen, and which are bound to the life-cycle of the React component. Using `useEffect` requires specifying dependencies. With MobX that isn't really needed, since MobX has already a way to automatically determine the dependencies of an effect, `autorun`. Combining `autorun` and coupling it to the life-cycle of the component using `useEffect` is luckily straightforward: ```javascript import { observer, useLocalObservable, useAsObservableSource } from "mobx-react-lite" import { useState } from "react" const TimerView = observer(() => { const timer = useLocalObservable(() => ({ secondsPassed: 0, increaseTimer() { this.secondsPassed++ } })) // Effect that triggers upon observable changes. useEffect( () => autorun(() => { if (timer.secondsPassed > 60) alert("Still there. It's a minute already?!!") }), [] ) // Effect to set up a timer, only for demo purposes. useEffect(() => { const handle = setInterval(timer.increaseTimer, 1000) return () => { clearInterval(handle) } }, []) return Seconds passed: {timer.secondsPassed} }) ReactDOM.render(
{user.name}
))
```
In the above listing React will unnecessarily need to reconcile all `TodoView` components when the `user.name` changes. They won't re-render, but the reconcile process is expensive in itself.
Good:
```javascript
const MyComponent = observer(({ todos, user }) => (
-
{todos.map(todo => (
{user.name}
))
const TodosView = observer(({ todos }) => (
-
{todos.map(todo => (
**Example:** the data and effect functions
In the example below, the reaction is only triggered once, when `isHungry` changes. Changes to `giraffe.energyLevel`, which is used by the _effect_ function, do not cause the _effect_ function to be executed. If you wanted `reaction` to respond to this as well, you would have to also access it in the _data_ function and return it. ```javascript import { makeAutoObservable, reaction } from "mobx" class Animal { name energyLevel constructor(name) { this.name = name this.energyLevel = 100 makeAutoObservable(this) } reduceEnergy() { this.energyLevel -= 10 } get isHungry() { return this.energyLevel < 50 } } const giraffe = new Animal("Gary") reaction( () => giraffe.isHungry, isHungry => { if (isHungry) { console.log("Now I'm hungry!") } else { console.log("I'm not hungry!") } console.log("Energy level:", giraffe.energyLevel) } ) console.log("Now let's change state!") for (let i = 0; i < 10; i++) { giraffe.reduceEnergy() } ``` Output: ``` Now let's change state! Now I'm hungry! Energy level: 40 ```**Example:** dispose of things in a reactive way
`when` is really useful for disposing or canceling of things in a reactive way. For example: ```javascript import { when, makeAutoObservable } from "mobx" class MyResource { constructor() { makeAutoObservable(this, { dispose: false }) when( // Once... () => !this.isVisible, // ... then. () => this.dispose() ) } get isVisible() { // Indicate whether this item is visible. } dispose() { // Clean up some resources. } } ``` As soon as `isVisible` becomes `false`, the `dispose` method is called that then does some cleanup for `MyResource`.**Example:** memory leak
```javascript class Vat { value = 1.2 constructor() { makeAutoObservable(this) } } const vat = new Vat() class OrderLine { price = 10 amount = 1 constructor() { makeAutoObservable(this) // This autorun will be GC-ed together with the current orderline // instance as it only uses observables from `this`. It's not strictly // necessary to dispose of it once an OrderLine instance is deleted. this.disposer1 = autorun(() => { doSomethingWith(this.price * this.amount) }) // This autorun won't be GC-ed together with the current orderline // instance, since vat keeps a reference to notify this autorun, which // in turn keeps 'this' in scope. this.disposer2 = autorun(() => { doSomethingWith(this.price * this.amount * vat.value) }) } dispose() { // So, to avoid subtle memory issues, always call the // disposers when the reactions are no longer needed. this.disposer1() this.disposer2() } } ```**Example:** using DisposableStack
```javascript function createSomeDisposableResource() {} class Vat { value = 1.2 constructor() { makeAutoObservable(this) } } const vat = new Vat() class OrderLine { price = 10 amount = 1 disposableStack = new DisposableStack() someDisposableResource constructor() { makeAutoObservable(this) this.disposableStack.use(autorun(() => { doSomethingWith(this.price * this.amount) })) this.disposableStack.use(autorun(() => { doSomethingWith(this.price * this.amount * vat.value) })) this.someDisposableResource = this.disposableStack.use(createSomeDisposableResource()) } [Symbol.dispose]() { this.disposableStack[Symbol.dispose](); } } ```When used with promise version of `when`, the promise rejects with the "WHEN_ABORTED" error. ### `onError` By default, any exception thrown inside an reaction will be logged, but not further thrown. This is to make sure that an exception in one reaction does not prevent the scheduled execution of other, possibly unrelated reactions. This also allows reactions to recover from exceptions. Throwing an exception does not break the tracking done by MobX, so subsequent runs of the reaction might complete normally again if the cause for the exception is removed. This option allows overriding that behavior. It is possible to set a global error handler or to disable catching errors completely using [configure](configuration.md#disableerrorboundaries-boolean). ### `scheduler` _(autorun, reaction)_ Set a custom scheduler to determine how re-running the autorun function should be scheduled. It takes a function that should be invoked at some point in the future, for example: `{ scheduler: run => { setTimeout(run, 1000) }}` ### `equals`: (reaction) Set to `comparer.default` by default. If specified, this comparer function is used to compare the previous and next values produced by the _data_ function. The _effect_ function is only invoked if this function returns false. Check out the [Built-in comparers](computeds.md#built-in-comparers) section. --- --- title: Updating state using actions hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../actions.md) --- --- title: MobX API overview hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../api.md) --- --- title: Running side effects with reactions hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../reactions.md) --- --- title: Computeds with arguments hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../computeds-with-args.md) --- --- title: Deriving information with computeds hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../computeds.md) --- --- title: Configuration hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../configuration.md) --- --- title: Creating custom observables hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../custom-observables.md) --- --- title: MobX-utils hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../mobx-utils.md) --- --- title: Observable modifiers hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../observable-state.md#available-annotations) --- --- title: Collection utilities hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../collection-utilities.md) --- --- title: Observable Objects hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../api.md#observableobject) --- --- title: Creating observable state hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../observable-state.md) --- --- title: Intercept & Observe hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../intercept-and-observe.md) --- --- title: Creating lazy observables hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../lazy-observables.md) --- --- title: Observable Sets hide_title: true --- # This document has been updated and moved [Please click on this link to open the updated version.](../api.md#observableset) --- --- title: Subclassing sidebar_label: Subclassing hide_title: true --- # Subclassing Subclassing is supported with [limitations](#limitations). Most notably you can only **override actions/flows/computeds on prototype** - you cannot override _[field declarations](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#field_declarations)_. Use the `override` annotation for methods/getters overridden in a subclass - see example below. Try to keep things simple and prefer composition over inheritance. ```javascript import { makeObservable, observable, computed, action, override } from "mobx" class Parent { // Annotated instance fields are NOT overridable observable = 0 arrowAction = () => {} // Non-annotated instance fields are overridable overridableArrowAction = action(() => {}) // Annotated prototype methods/getters are overridable action() {} actionBound() {} get computed() {} constructor(value) { makeObservable(this, { observable: observable, arrowAction: action action: action, actionBound: action.bound, computed: computed, }) } } class Child extends Parent { /* --- INHERITED --- */ // THROWS - TypeError: Cannot redefine property // observable = 5 // arrowAction = () = {} // OK - not annotated overridableArrowAction = action(() => {}) // OK - prototype action() {} actionBound() {} get computed() {} /* --- NEW --- */ childObservable = 0; childArrowAction = () => {} childAction() {} childActionBound() {} get childComputed() {} constructor(value) { super() makeObservable(this, { // inherited action: override, actionBound: override, computed: override, // new childObservable: observable, childArrowAction: action childAction: action, childActionBound: action.bound, childComputed: computed, }) } } ``` ## Limitations 1. Only `action`, `computed`, `flow`, `action.bound` defined **on prototype** can be **overridden** by subclass. 1. Field can't be re-annotated in subclass, except with `override`. 1. `makeAutoObservable` does not support subclassing. 1. Extending builtins (`ObservableMap`, `ObservableArray`, etc) is not supported. 1. You can't provide different options to `makeObservable` in subclass. 1. You can't mix annotations/decorators in single inheritance chain. 1. [All other limitations apply as well](observable-state.html#limitations) ### `TypeError: Cannot redefine property` If you see this, you're probably trying to **override arrow function** in subclass `x = () => {}`. That's not possible because **all annotated** fields of classes are **non-configurable** ([see limitations](observable-state.md#limitations)). You have two options:
1. Move function to prototype and use `action.bound` annotation instead
```javascript class Parent { // action = () => {}; // => action() {} constructor() { makeObservable(this, { action: action.bound }) } } class Child { action() {} constructor() { super() makeObservable(this, { action: override }) } } ```2. Remove `action` annotation and wrap the function in action manually: `x = action(() => {})`
```javascript class Parent { // action = () => {}; // => action = action(() => {}) constructor() { makeObservable(this, {}) // <-- annotation removed } } class Child { action = action(() => {}) constructor() { super() makeObservable(this, {}) // <-- annotation removed } } ```Tip: Prefer classes, plain objects or decorators? MobX supports many styles.
This example can be shortened using [`makeAutoObservable`](observable-state.md), but by being explicit we can showcase the different concepts in greater detail. Note that MobX doesn't dictate an object style, plain objects instead can be used as well, as can decorators for even more concise classes. See the page for more details.-
{todoList.todos.map(todo => (