Need help with mobx-react?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

mobxjs
4.7K Stars 365 Forks MIT License 949 Commits 0 Opened issues

Description

React bindings for MobX

Services available

!
?

Need anything else?

Contributors list

mobx-react


🚨🚨🚨 This repo has been moved to mobx


CircleCI CDNJS Minzipped size

TypeScriptcode style: prettier

Discuss on Github View changelog

Package with React component wrapper for combining React with MobX. Exports the

observer
decorator and other utilities. For documentation, see the MobX project. There is also work-in-progress user guide for additional information. This package supports both React and React Native.

Choosing your version

There are currently two actively maintained versions of mobx-react:

| NPM Version | Support MobX version | Supported React versions | Supports hook based components | | ----------- | -------------------- | ------------------------ | -------------------------------------------------------------------------------- | | v7 | 6.* | 16.8+ | Yes | | v6 | 4._ / 5._ | 16.8+ | Yes | | v5 | 4._ / 5._ | 0.13+ | No, but it is possible to use

 sections inside hook based components |

mobx-react 6 / 7 is a repackage of the smaller mobx-react-lite package + following features from the

[email protected]
package added:
  • Support for class based components for
    observer
    and
    @observer
  • Provider / inject
    to pass stores around (but consider to use
    React.createContext
    instead)
  • PropTypes
    to describe observable based property checkers (but consider to use TypeScript instead)
  • The
    disposeOnUnmount
    utility / decorator to easily clean up resources such as reactions created in your class based components.

Installation

npm install mobx-react --save

Or CDN: https://unpkg.com/mobx-react (UMD namespace:

mobxReact
)
import { observer } from "mobx-react"

This package provides the bindings for MobX and React. See the official documentation for how to get started.

For greenfield projects you might want to consider to use mobx-react-lite, if you intend to only use function based components.

React.createContext
can be used to pass stores around.

API documentation

Please check mobx.js.org for the general documentation. The documentation below highlights some specifics.

observer(component)

Function (and decorator) that converts a React component definition, React component class, or stand-alone render function, into a reactive component. A converted component will track which observables are used by its effective

render
and automatically re-render the component when one of these values changes.

Functional Components

React.memo
is automatically applied to functional components provided to
observer
.
observer
does not accept a functional component already wrapped in
React.memo
, or an
observer
, in order to avoid consequences that might arise as a result of wrapping it twice.

Class Components

When using component classes,

this.props
and
this.state
will be made observables, so the component will react to all changes in props and state that are used by
render
.

shouldComponentUpdate
is not supported. As such, it is recommended that class components extend
React.PureComponent
. The
observer
will automatically patch non-pure class components with an internal implementation of
React.PureComponent
if necessary.

See the MobX documentation for more details.

import { observer } from "mobx-react"

// ---- ES6 syntax ---- const TodoView = observer( class TodoView extends React.Component { render() { return

{this.props.todo.title}
} } )

// ---- ESNext syntax with decorator syntax enabled ---- @observer class TodoView extends React.Component { render() { return

{this.props.todo.title}
} }

// ---- or just use function components: ---- const TodoView = observer(({ todo }) =>

{todo.title}
)

Observer

Observer
is a React component, which applies
observer
to an anonymous region in your component. It takes as children a single, argumentless function which should return exactly one React component. The rendering in the function will be tracked and automatically re-rendered when needed. This can come in handy when needing to pass render function to external components (for example the React Native listview), or if you dislike the
observer
decorator / function.
class App extends React.Component {
    render() {
        return (
            
{this.props.person.name} {() =>
{this.props.person.name}
}
) } }

const person = observable({ name: "John" })

ReactDOM.render(, document.body) person.name = "Mike" // will cause the Observer region to re-render

In case you are a fan of render props, you can use that instead of children. Be advised, that you cannot use both approaches at once, children have a precedence. Example

class App extends React.Component {
    render() {
        return (
            
{this.props.person.name}
{this.props.person.name}
} />
) } }

const person = observable({ name: "John" })

ReactDOM.render(, document.body) person.name = "Mike" // will cause the Observer region to re-render

useLocalObservable
hook

User guide

Local observable state can be introduced by using the

useLocalObservable
hook, that runs once to create an observable store. A quick example would be:
import { useLocalObservable, Observer } from "mobx-react-lite"

const Todo = () => { const todo = useLocalObservable(() => ({ title: "Test", done: true, toggle() { this.done = !this.done } }))

return (
    <observer>
        {() =&gt; (
            <h1 onclick="{todo.toggle}">
                {todo.title} {todo.done ? "[DONE]" : "[TODO]"}
            </h1>
        )}
    </observer>
)

}

When using

useLocalObservable
, all properties of the returned object will be made observable automatically, getters will be turned into computed properties, and methods will be bound to the store and apply mobx transactions automatically. If new class instances are returned from the initializer, they will be kept as is.

It is important to realize that the store is created only once! It is not possible to specify dependencies to force re-creation, nor should you directly be referring to props for the initializer function, as changes in those won't propagate.

Instead, if your store needs to refer to props (or

useState
based local state), the
useLocalObservable
should be combined with the
useAsObservableSource
hook, see below.

Note that in many cases it is possible to extract the initializer function to a function outside the component definition. Which makes it possible to test the store itself in a more straight-forward manner, and avoids creating the initializer closure on each re-render.

Note: using

useLocalObservable
is mostly beneficial for really complex local state, or to obtain more uniform code base. Note that using a local store might conflict with future React features like concurrent rendering.

Server Side Rendering with
enableStaticRendering

When using server side rendering, normal lifecycle hooks of React components are not fired, as the components are rendered only once. Since components are never unmounted,

observer
components would in this case leak memory when being rendered server side. To avoid leaking memory, call
enableStaticRendering(true)
when using server side rendering.
import { enableStaticRendering } from "mobx-react"

enableStaticRendering(true)

This makes sure the component won't try to react to any future data changes.

Which components should be marked with
observer
?

The simple rule of thumb is: all components that render observable data. If you don't want to mark a component as observer, for example to reduce the dependencies of a generic component package, make sure you only pass it plain data.

Enabling decorators (optional)

Decorators are currently a stage-2 ESNext feature. How to enable them is documented here.

Should I still use smart and dumb components?

See this thread. TL;DR: the conceptual distinction makes a lot of sense when using MobX as well, but use

observer
on all components.

PropTypes

MobX-react provides the following additional

PropTypes
which can be used to validate against MobX structures:
  • observableArray
  • observableArrayOf(React.PropTypes.number)
  • observableMap
  • observableObject
  • arrayOrObservableArray
  • arrayOrObservableArrayOf(React.PropTypes.number)
  • objectOrObservableObject

Use

import { PropTypes } from "mobx-react"
to import them, then use for example
PropTypes.observableArray

Provider
and
inject

See also the migration guide to React Hooks.

Note: usually there is no need anymore to use

Provider
/
inject
in new code bases; most of its features are now covered by
React.createContext
.

Provider
is a component that can pass stores (or other stuff) using React's context mechanism to child components. This is useful if you have things that you don't want to pass through multiple layers of components explicitly.

inject
can be used to pick up those stores. It is a higher order component that takes a list of strings and makes those stores available to the wrapped component.

Example (based on the official context docs):

@inject("color")
@observer
class Button extends React.Component {
    render() {
        return {this.props.children}
    }
}

class Message extends React.Component { render() { return (

{this.props.text} Delete
) } }

class MessageList extends React.Component { render() { const children = this.props.messages.map(message => ) return (

{children}
) } }

Notes:

  • It is possible to read the stores provided by
    Provider
    using
    React.useContext
    , by using the
    MobXProviderContext
    context that can be imported from
    mobx-react
    .
  • If a component asks for a store and receives a store via a property with the same name, the property takes precedence. Use this to your advantage when testing!
  • When using both
    @inject
    and
    @observer
    , make sure to apply them in the correct order:
    observer
    should be the inner decorator,
    inject
    the outer. There might be additional decorators in between.
  • The original component wrapped by
    inject
    is available as the
    wrappedComponent
    property of the created higher order component.

"The set of provided stores has changed" error

Values provided through

Provider
should be final. Make sure that if you put things in
context
that might change over time, that they are
@observable
or provide some other means to listen to changes, like callbacks. However, if your stores will change over time, like an observable value of another store, MobX will throw an error. This restriction exists mainly for legacy reasons. If you have a scenario where you need to modify the set of stores, please leave a comment about it in this issue https://github.com/mobxjs/mobx-react/issues/745. Or a preferred way is to use React Context directly which does not have this restriction.

Inject as function

The above example in ES5 would start like:

var Button = inject("color")(
    observer(
        class Button extends Component {
            /* ... etc ... */
        }
    )
)

A functional stateless component would look like:

var Button = inject("color")(
    observer(({ color }) => {
        /* ... etc ... */
    })
)

Customizing inject

Instead of passing a list of store names, it is also possible to create a custom mapper function and pass it to inject. The mapper function receives all stores as argument, the properties with which the components are invoked and the context, and should produce a new set of properties, that are mapped into the original:

mapperFunction: (allStores, props, context) => additionalProps

Since version 4.0 the

mapperFunction
itself is tracked as well, so it is possible to do things like:
const NameDisplayer = ({ name }) => 

{name}

const UserNameDisplayer = inject(stores => ({ name: stores.userStore.name }))(NameDisplayer)

const user = mobx.observable({ name: "Noa" })

const App = () => ( )

ReactDOM.render(, document.body)

N.B. note that in this specific case neither

NameDisplayer
nor
UserNameDisplayer
needs to be decorated with
observer
, since the observable dereferencing is done in the mapper function

Using
PropTypes
and
defaultProps
and other static properties in combination with
inject

Inject wraps a new component around the component you pass into it. This means that assigning a static property to the resulting component, will be applied to the HoC, and not to the original component. So if you take the following example:

const UserName = inject("userStore")(({ userStore, bold }) => someRendering())

UserName.propTypes = { bold: PropTypes.boolean.isRequired, userStore: PropTypes.object.isRequired // will always fail }

The above propTypes are incorrect,

bold
needs to be provided by the caller of the
UserName
component and is checked by React. However,
userStore
does not need to be required! Although it is required for the original stateless function component, it is not required for the resulting inject component. After all, the whole point of that component is to provide that
userStore
itself.

So if you want to make assertions on the data that is being injected (either stores or data resulting from a mapper function), the propTypes should be defined on the wrapped component. Which is available through the static property

wrappedComponent
on the inject component:
const UserName = inject("userStore")(({ userStore, bold }) => someRendering())

UserName.propTypes = { bold: PropTypes.boolean.isRequired // could be defined either here ... }

UserName.wrappedComponent.propTypes = { // ... or here userStore: PropTypes.object.isRequired // correct }

The same principle applies to

defaultProps
and other static React properties. Note that it is not allowed to redefine
contextTypes
on
inject
components (but is possible to define it on
wrappedComponent
)

Finally, mobx-react will automatically move non React related static properties from wrappedComponent to the inject component so that all static fields are actually available to the outside world without needing

.wrappedComponent
.

Strongly typing inject

With TypeScript

inject
also accepts a function (
(allStores, nextProps, nextContext) => additionalProps
) that can be used to pick all the desired stores from the available stores like this. The
additionalProps
will be merged into the original
nextProps
before being provided to the next component.
import { IUserStore } from "myStore"

@inject(allStores => ({ userStore: allStores.userStore as IUserStore })) class MyComponent extends React.Component { /* etc */ }

Make sure to mark

userStore
as an optional property. It should not (necessarily) be passed in by parent components at all!

Note: If you have strict null checking enabled, you could muffle the nullable type by using the

!
operator:
public render() {
   const {a, b} = this.store!
   // ...
}

By migrating to React Hooks you can avoid problems with TypeScript.

Testing store injection

It is allowed to pass any declared store in directly as a property as well. This makes it easy to set up individual component tests without a provider.

So if you have in your app something like:

    

In your test you can easily test the

Person
component by passing the necessary store as prop directly:
const profile = new Profile()
const mountedComponent = mount(
   
)

Bear in mind that using shallow rendering won't provide any useful results when testing injected components; only the injector will be rendered. To test with shallow rendering, instantiate the

wrappedComponent
instead:
shallow()

disposeOnUnmount(componentInstance, propertyKey | function | function[])

Function (and decorator) that makes sure a function (usually a disposer such as the ones returned by

reaction
,
autorun
, etc.) is automatically executed as part of the componentWillUnmount lifecycle event.
import { disposeOnUnmount } from "mobx-react"

class SomeComponent extends React.Component { // decorator version @disposeOnUnmount someReactionDisposer = reaction(...)

// decorator version with arrays
@disposeOnUnmount
someReactionDisposers = [
    reaction(...),
    reaction(...)
]


// function version over properties
someReactionDisposer = disposeOnUnmount(this, reaction(...))

// function version inside methods
componentDidMount() {
    // single function
    disposeOnUnmount(this, reaction(...))

    // or function array
    disposeOnUnmount(this, [
        reaction(...),
        reaction(...)
    ])
}

}

DevTools

[email protected]
and higher are no longer compatible with the mobx-react-devtools. That is, the MobX react devtools will no longer show render timings or dependency trees of the component. The reason is that the standard React devtools are also capable of highlighting re-rendering components. And the dependency tree of a component can now be inspected by the standard devtools as well, as shown in the image below:

hooks.png

FAQ

Should I use

observer
for each component?

You should use

observer
on every component that displays observable data. Even the small ones.
observer
allows components to render independently from their parent and in general this means that the more you use
observer
, the better the performance become. The overhead of
observer
itself is negligible. See also Do child components need
@observer
?

I see React warnings about

forceUpdate
/
setState
from React

The following warning will appear if you trigger a re-rendering between instantiating and rendering a component:

Warning: forceUpdate(...): Cannot update during an existing state transition (such as within `render`). Render methods should be a pure function of props and state.`

-- or --

Warning: setState(...): Cannot update during an existing state transition (such as within `render` or another component's constructor). Render methods should be a pure function of props and state; constructor side-effects are an anti-pattern, but can be moved to `componentWillMount`.

Usually this means that (another) component is trying to modify observables used by this components in their

constructor
or
getInitialState
methods. This violates the React Lifecycle,
componentWillMount
should be used instead if state needs to be modified before mounting.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.