# mobx-react [![CircleCI](https://circleci.com/gh/mobxjs/mobx-react.svg?style=svg)](https://circleci.com/gh/mobxjs/mobx-react) [![CDNJS](https://img.shields.io/cdnjs/v/mobx-react.svg)](https://cdnjs.com/libraries/mobx-react) [![Minzipped size](https://img.shields.io/bundlephobia/minzip/mobx-react.svg)](https://bundlephobia.com/result?p=mobx-react) [![Discuss on Github](https://img.shields.io/badge/discuss%20on-GitHub-orange)](https://github.com/mobxjs/mobx/discussions) [![View changelog](https://img.shields.io/badge/changelogs.xyz-Explore%20Changelog-brightgreen)](https://changelogs.xyz/mobx-react) Package with React component wrapper for combining React with MobX. Exports the `observer` decorator and other utilities. For documentation, see the [MobX](https://mobx.js.org) project. This package supports both React and React Native. ## Compatibility matrix Only the latest version is actively maintained. If you're missing a fix or a feature in older version, consider upgrading or using [patch-package](https://www.npmjs.com/package/patch-package) | NPM Version | Support MobX version | Supported React versions | Added support for: | | ----------- | -------------------- | ------------------------ | -------------------------------------------------------------------------------- | | v9 | 6.\* | >16.8 | Hooks, React 18.2 in strict mode | | v7 | 6.\* | >16.8 < 18.2 | Hooks | | v6 | 4.\* / 5.\* | >16.8 <18 | Hooks | | v5 | 4.\* / 5.\* | >0.13 <18 | 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](https://github.com/mobxjs/mobx/tree/main/packages/mobx-react-lite) package + following features from the `mobx-react@5` 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`) ```javascript import { observer } from "mobx-react" ``` This package provides the bindings for MobX and React. See the [official documentation](https://mobx.js.org/react-integration.html) for how to get started. For greenfield projects you might want to consider to use [mobx-react-lite](https://github.com/mobxjs/mobx/tree/main/packages/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](https://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 `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. Extending `observer` class components is not supported. Always apply `observer` only on the last class in the inheritance chain. See the [MobX](https://mobx.js.org/react-integration.html#react-integration) documentation for more details. ```javascript 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}

) ``` ##### Note on using props and state in derivations `mobx-react` version 6 and lower would automatically turn `this.state` and `this.props` into observables. This has the benefit that computed properties and reactions were able to observe those. However, since this pattern is fundamentally incompatible with `StrictMode` in React 18.2 and higher, this behavior has been removed in React 18. As a result, we recommend to no longer mark properties as `@computed` in observer components if they depend on `this.state` or `this.props`. ```javascript @observer class Doubler extends React.Component<{ counter: number }> { @computed // BROKEN! <-- @computed should be removed in mobx-react > 7 get doubleValue() { // Changes to this.props will no longer be detected properly, to fix it, // remove the @computed annotation. return this.props * 2 } render() { return

{this.doubleValue}

} } ``` Similarly, reactions will no longer respond to `this.state` / `this.props`. This can be overcome by creating an observable copy: ```javascript @observer class Alerter extends React.Component<{ counter: number }> { @observable observableCounter: number reactionDisposer constructor(props) { this.observableCounter = counter } componentDidMount() { // set up a reaction, by observing the observable, // rather than the prop which is non-reactive: this.reactionDisposer = autorun(() => { if (this.observableCounter > 10) { alert("Reached 10!") } }) } componentDidUpdate() { // sync the observable from props this.observableCounter = this.props.counter } componentWillUnmount() { this.reactionDisposer() } render() { return

{this.props.counter}

} } ``` MobX-react will try to detect cases where `this.props`, `this.state` or `this.context` are used by any other derivation than the `render` method of the owning component and throw. This is to make sure that neither computed properties, nor reactions, nor other components accidentally rely on those fields to be reactive. This includes cases where a render callback is passed to a child, that will read from the props or state of a parent component. As a result, passing a function that might later read a property of a parent in a reactive context will throw as well. Instead, when using a callback function that is being passed to an `observer` based child, the capture should be captured locally first: ```javascript @observer class ChildWrapper extends React.Component<{ counter: number }> { render() { // Collapsible is an observer component that should respond to this.counter, // if it is expanded // BAD: return

{this.props.counter}

} /> // GOOD: (causes to pass down a fresh callback whenever counter changes, // that doesn't depend on its parents props) const counter = this.props.counter return

{counter}

} /> } } ``` ### `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. ```javascript 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 ```javascript class App extends React.Component { render() { return (

{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 Local observable state can be introduced by using the `useLocalObservable` hook, that runs once to create an observable store. A quick example would be: ```javascript import { useLocalObservable, Observer } from "mobx-react-lite" const Todo = () => { const todo = useLocalObservable(() => ({ title: "Test", done: true, toggle() { this.done = !this.done } })) return ( {() => (

{todo.title} {todo.done ? "[DONE]" : "[TODO]"}

)} ) } ``` 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. ```javascript 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](https://mobx.js.org/enabling-decorators.html#enabling-decorators-). ### Should I still use smart and dumb components? See this [thread](https://www.reddit.com/r/reactjs/comments/4vnxg5/free_eggheadio_course_learn_mobx_react_in_30/d61oh0l). 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` _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](https://facebook.github.io/react/docs/context.html#passing-info-automatically-through-a-tree)): ```javascript @inject("color") @observer class Button extends React.Component { render() { return } } class Message extends React.Component { render() { return (

{this.props.text}

) } } 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](https://reactjs.org/docs/context.html) directly which does not have this restriction. #### Inject as function The above example in ES5 would start like: ```javascript var Button = inject("color")( observer( class Button extends Component { /* ... etc ... */ } ) ) ``` A functional stateless component would look like: ```javascript 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: ```javascript const NameDisplayer = ({ name }) =>

{name}

	Stars	Issues	Version	Updated	Created
flux	17,440	6	4.0.4	a year ago	13 years ago
mobx	27,462	66	6.13.2	13 days ago	9 years ago
mobx-react	27,462	66	9.1.1	6 months ago	9 years ago
redux	60,796	37	5.0.1	9 months ago	13 years ago

flux vs mobx vs mobx-react vs redux

Downloads in past1 Month3 Months6 Months1 Year2 Years5 YearsAll time

Stats

Sick of boring JavaScript newsletters?

Downloads in past