Usage:

While MobX works independently from React, they are most commonly used together. In The gist of MobX you have already seen the most important part of this integration: the observer HoC that you can wrap around a React component.

observer is provided by a separate React bindings package you choose during installation. In this example, we're going to use the more lightweight mobx-react-lite package.

Hint: you can play with the above example yourself on CodeSandbox.

The observer HoC automatically subscribes React components to any observables that are used during rendering. As a result, components will automatically re-render when relevant observables change. It also makes sure that components don't re-render when there are no relevant changes. So, observables that are accessible by the component, but not actually read, won't ever cause a re-render.

In practice this makes MobX applications very well optimized out of the box and they typically don't need any additional code to prevent excessive rendering.

For observer to work, it doesn't matter how the observables arrive in the component, only that they are read. Reading observables deeply is fine, complex expression like todos[0].author.displayName work out of the box. This makes the subscription mechanism much more precise and efficient compared to other frameworks in which data dependencies have to be declared explicitly or be pre-computed (e.g. selectors).

There is great flexibility in how state is organized, since it doesn't matter (technically that is) which observables we read or where observables originated from. The examples below demonstrate different patterns on how external and local observable state can be used in components wrapped with observer.

Observables can be passed into components as props (as in the example above):

Since it doesn't matter how we got the reference to an observable, we can consume observables from outer scopes directly (including from imports, etc.):

Using observables directly works very well, but since this typically introduces module state, this pattern might complicate unit testing. Instead, we recommend using React Context instead.

React Context is a great mechanism to share observables with an entire subtree:

Note that we don't recommend ever replacing the value of a Provider with a different one. Using MobX, there should be no need for that, since the observable that is shared can be updated itself.

Since observables used by observer can come from anywhere, they can be local state as well. Again, different options are available for us.

The simplest way to use local observable state is to store a reference to an observable class with useState. Note that, since we typically don't want to replace the reference, we totally ignore the updater function returned by useState:

If you want to automatically update the timer like we did in the original example, useEffect could be used in typical React fashion:

As stated before, instead of using classes, it is possible to directly create observable objects. We can leverage observable for that:

The combination const [store] = useState(() => observable({ /* something */})) is quite common. To make this pattern simpler the useLocalObservable hook is exposed from mobx-react-lite package, making it possible to simplify the earlier example to:

In general, we recommend to not resort to MobX observables for local component state too quickly, as this can theoretically lock you out of some features of React's Suspense mechanism. As a rule of thumb, use MobX observables when the state captures domain data that is shared among components (including children). Such as todo items, users, bookings, etc.

State that only captures UI state, like loading state, selections, etc, might be better served by the useState hook, since this will allow you to leverage React suspense features in the future.

Using observables inside React components adds value as soon as they are either 1) deep, 2) have computed values or 3) are shared with other observer components.

You might be wondering, when do I apply observer? The rule of thumb is: apply observer to all components that read observable data.

observer only enhances the component you are decorating, not the components called by it. So usually all your components should be wrapped by observer. Don't worry, this is not inefficient. On the contrary, more observer components make rendering more efficient as updates become more fine-grained.

observer works best if you pass object references around as long as possible, and only read their properties inside the observer based components that are going to render them into the DOM / low-level components. In other words, observer reacts to the fact that you 'dereference' a value from an object.

In the above example, the TimerView component would not react to future changes if it was defined as follows, because the .secondsPassed is not read inside the observer component, but outside, and is hence not tracked:

Note that this is a different mindset from other libraries like react-redux, where it is a good practice to dereference early and pass primitives down, to better leverage memoization. If the problem is not entirely clear, make sure to check out the Understanding reactivity section.

Components wrapped with observer only subscribe to observables used during their own rendering of the component. So if observable objects / arrays / maps are passed to child components, those have to be wrapped with observer as well. This is also true for any callback based components.

If you want to pass observables to a component that isn't an observer, either because it is a third-party component, or because you want to keep that component MobX agnostic, you will have to convert the observables to plain JavaScript values or structures before passing them on.

To elaborate on the above, take the following example observable todo object, a TodoView component (observer) and an imaginary GridRow component that takes a column / value mapping, but which isn't an observer:

Imagine the same example, where GridRow takes an onRender callback instead. Since onRender is part of the rendering cycle of GridRow, rather than TodoView's render (even though that is where it syntactically appears), we have to make sure that the callback component uses an observer component. Or, we can create an in-line anonymous observer using :

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 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:

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 Reacmo? 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:

Check out mobx-react docs for more information.

Tip: nice component names in React DevTools React DevTools uses the display name information of components to properly display the component hierarchy.

If you use:

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:

Transpilers (like Babel or TypeScript) infer component name from the variable name:

Infer from the variable name again, using default export:

[Broken] Set displayName explicitly:

This is broken in React 16 at the time of writing; mobx-react observer uses a Reacmo 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.

In practice you will rarely need this pattern, since return Seconds passed: {timer.secondsPassed - offset} is a much simpler, albeit slightly less efficient solution.

{🚀} 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:

Note that we return the disposer created by autorun from our effect function. This is important, since it makes sure the autorun gets cleaned up once the component unmounts!

The dependency array can typically be left empty, unless a non-observable value should trigger a re-run of the autorun, in which case you will need to add it there. To make your linter happy, you can define timer (in the above example) as a dependency. That is safe and has no further effect, since the reference will never actually change.

If you'd rather explicitly define which observables should trigger the effect, use reaction instead of autorun, beyond that the pattern remains identical.

Check out the React optimizations {🚀} section.

Help! My component isn't re-rendering...