{"id":13461525,"url":"https://github.com/mobxjs/mobx-react","last_synced_at":"2025-09-28T06:31:47.905Z","repository":{"id":39178305,"uuid":"41543133","full_name":"mobxjs/mobx-react","owner":"mobxjs","description":"React bindings for MobX","archived":true,"fork":false,"pushed_at":"2020-12-30T16:19:32.000Z","size":2388,"stargazers_count":4854,"open_issues_count":0,"forks_count":350,"subscribers_count":85,"default_branch":"master","last_synced_at":"2024-09-21T17:40:11.080Z","etag":null,"topics":["javascript","mobx","react","react-components","reactive-programming"],"latest_commit_sha":null,"homepage":"https://mobx.js.org/react-integration.html","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mobxjs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"open_collective":"mobx"}},"created_at":"2015-08-28T11:09:05.000Z","updated_at":"2024-09-14T12:04:04.000Z","dependencies_parsed_at":"2022-08-01T07:59:14.194Z","dependency_job_id":null,"html_url":"https://github.com/mobxjs/mobx-react","commit_stats":null,"previous_names":["mweststrate/mobservable-react"],"tags_count":121,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobxjs%2Fmobx-react","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobxjs%2Fmobx-react/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobxjs%2Fmobx-react/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mobxjs%2Fmobx-react/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mobxjs","download_url":"https://codeload.github.com/mobxjs/mobx-react/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219873797,"owners_count":16554510,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","mobx","react","react-components","reactive-programming"],"created_at":"2024-07-31T11:00:42.320Z","updated_at":"2025-09-28T06:31:42.528Z","avatar_url":"https://github.com/mobxjs.png","language":"TypeScript","readme":"# mobx-react\n\n----\n\n## 🚨🚨🚨 This repo has been moved to [mobx](https://github.com/mobxjs/mobx/tree/main/packages/mobx-react)\n\n----\n\n[![CircleCI](https://circleci.com/gh/mobxjs/mobx-react.svg?style=svg)](https://circleci.com/gh/mobxjs/mobx-react)\n[![CDNJS](https://img.shields.io/cdnjs/v/mobx-react.svg)](https://cdnjs.com/libraries/mobx-react)\n[![Minzipped size](https://img.shields.io/bundlephobia/minzip/mobx-react-lite.svg)](https://bundlephobia.com/result?p=mobx-react-lite)\n\n[![TypeScript](https://badges.frapsoft.com/typescript/code/typescript.svg?v=101)](https://github.com/ellerbrock/typescript-badges/)[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)\n\n[![Discuss on Github](https://img.shields.io/badge/discuss%20on-GitHub-orange)](https://github.com/mobxjs/mobx/discussions)\n[![View changelog](https://img.shields.io/badge/changelogs.xyz-Explore%20Changelog-brightgreen)](https://changelogs.xyz/mobx-react)\n\nPackage with React component wrapper for combining React with MobX.\nExports the `observer` decorator and other utilities.\nFor documentation, see the [MobX](https://mobxjs.github.io/mobx) project.\nThere is also work-in-progress [user guide](https://mobx-react.js.org) for additional information.\nThis package supports both React and React Native.\n\n## Choosing your version\n\nThere are currently two actively maintained versions of mobx-react:\n\n| NPM Version | Support MobX version | Supported React versions | Supports hook based components                                                   |\n| ----------- | -------------------- | ------------------------ | -------------------------------------------------------------------------------- |\n| v7          | 6.\\*                 | 16.8+                    | Yes                                                                              |\n| v6          | 4._ / 5._            | 16.8+                    | Yes                                                                              |\n| v5          | 4._ / 5._            | 0.13+                    | No, but it is possible to use `\u003cObserver\u003e` sections inside hook based components |\n\nmobx-react 6 / 7 is a repackage of the smaller [mobx-react-lite](https://github.com/mobxjs/mobx-react-lite) package + following features from the `mobx-react@5` package added:\n\n-   Support for class based components for `observer` and `@observer`\n-   `Provider / inject` to pass stores around (but consider to use `React.createContext` instead)\n-   `PropTypes` to describe observable based property checkers (but consider to use TypeScript instead)\n-   The `disposeOnUnmount` utility / decorator to easily clean up resources such as reactions created in your class based components.\n\n## Installation\n\n`npm install mobx-react --save`\n\nOr CDN: https://unpkg.com/mobx-react (UMD namespace: `mobxReact`)\n\n```javascript\nimport { observer } from \"mobx-react\"\n```\n\nThis package provides the bindings for MobX and React.\nSee the [official documentation](https://mobx.js.org/react-integration.html) for how to get started.\n\nFor greenfield projects you might want to consider to use [mobx-react-lite](https://github.com/mobxjs/mobx-react-lite), if you intend to only use function based components. `React.createContext` can be used to pass stores around.\n\n## API documentation\n\nPlease check [mobx.js.org](https://mobx.js.org/) for the general documentation. The documentation below highlights some specifics.\n\n### `observer(component)`\n\nFunction (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.\n\n#### Functional Components\n\n`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.\n\n#### Class Components\n\nWhen 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`.\n\n`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.\n\nSee the [MobX](https://mobxjs.github.io/mobx/refguide/observer-component.html) documentation for more details.\n\n```javascript\nimport { observer } from \"mobx-react\"\n\n// ---- ES6 syntax ----\nconst TodoView = observer(\n    class TodoView extends React.Component {\n        render() {\n            return \u003cdiv\u003e{this.props.todo.title}\u003c/div\u003e\n        }\n    }\n)\n\n// ---- ESNext syntax with decorator syntax enabled ----\n@observer\nclass TodoView extends React.Component {\n    render() {\n        return \u003cdiv\u003e{this.props.todo.title}\u003c/div\u003e\n    }\n}\n\n// ---- or just use function components: ----\nconst TodoView = observer(({ todo }) =\u003e \u003cdiv\u003e{todo.title}\u003c/div\u003e)\n```\n\n### `Observer`\n\n`Observer` is a React component, which applies `observer` to an anonymous region in your component.\nIt takes as children a single, argumentless function which should return exactly one React component.\nThe rendering in the function will be tracked and automatically re-rendered when needed.\nThis can come in handy when needing to pass render function to external components (for example the React Native listview), or if you\ndislike the `observer` decorator / function.\n\n```javascript\nclass App extends React.Component {\n    render() {\n        return (\n            \u003cdiv\u003e\n                {this.props.person.name}\n                \u003cObserver\u003e{() =\u003e \u003cdiv\u003e{this.props.person.name}\u003c/div\u003e}\u003c/Observer\u003e\n            \u003c/div\u003e\n        )\n    }\n}\n\nconst person = observable({ name: \"John\" })\n\nReactDOM.render(\u003cApp person={person} /\u003e, document.body)\nperson.name = \"Mike\" // will cause the Observer region to re-render\n```\n\nIn 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.\nExample\n\n```javascript\nclass App extends React.Component {\n    render() {\n        return (\n            \u003cdiv\u003e\n                {this.props.person.name}\n                \u003cObserver render={() =\u003e \u003cdiv\u003e{this.props.person.name}\u003c/div\u003e} /\u003e\n            \u003c/div\u003e\n        )\n    }\n}\n\nconst person = observable({ name: \"John\" })\n\nReactDOM.render(\u003cApp person={person} /\u003e, document.body)\nperson.name = \"Mike\" // will cause the Observer region to re-render\n```\n\n### `useLocalObservable` hook\n\n[User guide](https://mobx-react.js.org/state-local)\n\nLocal observable state can be introduced by using the `useLocalObservable` hook, that runs once to create an observable store. A quick example would be:\n\n```javascript\nimport { useLocalObservable, Observer } from \"mobx-react-lite\"\n\nconst Todo = () =\u003e {\n    const todo = useLocalObservable(() =\u003e ({\n        title: \"Test\",\n        done: true,\n        toggle() {\n            this.done = !this.done\n        }\n    }))\n\n    return (\n        \u003cObserver\u003e\n            {() =\u003e (\n                \u003ch1 onClick={todo.toggle}\u003e\n                    {todo.title} {todo.done ? \"[DONE]\" : \"[TODO]\"}\n                \u003c/h1\u003e\n            )}\n        \u003c/Observer\u003e\n    )\n}\n```\n\nWhen 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.\n\nIt 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.\n\nInstead, if your store needs to refer to props (or `useState` based local state), the `useLocalObservable` should be combined with the `useAsObservableSource` hook, see below.\n\nNote 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.\n\n_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._\n\n### Server Side Rendering with `enableStaticRendering`\n\nWhen using server side rendering, normal lifecycle hooks of React components are not fired, as the components are rendered only once.\nSince components are never unmounted, `observer` components would in this case leak memory when being rendered server side.\nTo avoid leaking memory, call `enableStaticRendering(true)` when using server side rendering.\n\n```javascript\nimport { enableStaticRendering } from \"mobx-react\"\n\nenableStaticRendering(true)\n```\n\nThis makes sure the component won't try to react to any future data changes.\n\n### Which components should be marked with `observer`?\n\nThe simple rule of thumb is: _all components that render observable data_.\nIf 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.\n\n### Enabling decorators (optional)\n\nDecorators are currently a stage-2 ESNext feature. How to enable them is documented [here](https://github.com/mobxjs/mobx#enabling-decorators-optional).\n\n### Should I still use smart and dumb components?\n\nSee this [thread](https://www.reddit.com/r/reactjs/comments/4vnxg5/free_eggheadio_course_learn_mobx_react_in_30/d61oh0l).\nTL;DR: the conceptual distinction makes a lot of sense when using MobX as well, but use `observer` on all components.\n\n### `PropTypes`\n\nMobX-react provides the following additional `PropTypes` which can be used to validate against MobX structures:\n\n-   `observableArray`\n-   `observableArrayOf(React.PropTypes.number)`\n-   `observableMap`\n-   `observableObject`\n-   `arrayOrObservableArray`\n-   `arrayOrObservableArrayOf(React.PropTypes.number)`\n-   `objectOrObservableObject`\n\nUse `import { PropTypes } from \"mobx-react\"` to import them, then use for example `PropTypes.observableArray`\n\n### `Provider` and `inject`\n\nSee also [the migration guide to React Hooks](https://mobx-react.js.org/recipes-migration).\n\n_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`._\n\n`Provider` is a component that can pass stores (or other stuff) using React's context mechanism to child components.\nThis is useful if you have things that you don't want to pass through multiple layers of components explicitly.\n\n`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.\n\nExample (based on the official [context docs](https://facebook.github.io/react/docs/context.html#passing-info-automatically-through-a-tree)):\n\n```javascript\n@inject(\"color\")\n@observer\nclass Button extends React.Component {\n    render() {\n        return \u003cbutton style={{ background: this.props.color }}\u003e{this.props.children}\u003c/button\u003e\n    }\n}\n\nclass Message extends React.Component {\n    render() {\n        return (\n            \u003cdiv\u003e\n                {this.props.text} \u003cButton\u003eDelete\u003c/Button\u003e\n            \u003c/div\u003e\n        )\n    }\n}\n\nclass MessageList extends React.Component {\n    render() {\n        const children = this.props.messages.map(message =\u003e \u003cMessage text={message.text} /\u003e)\n        return (\n            \u003cProvider color=\"red\"\u003e\n                \u003cdiv\u003e{children}\u003c/div\u003e\n            \u003c/Provider\u003e\n        )\n    }\n}\n```\n\nNotes:\n\n-   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`.\n-   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!\n-   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.\n-   The original component wrapped by `inject` is available as the `wrappedComponent` property of the created higher order component.\n\n#### \"The set of provided stores has changed\" error\n\nValues 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.\nThis 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://mobx-react.js.org/recipes-context) directly which does not have this restriction.\n\n#### Inject as function\n\nThe above example in ES5 would start like:\n\n```javascript\nvar Button = inject(\"color\")(\n    observer(\n        class Button extends Component {\n            /* ... etc ... */\n        }\n    )\n)\n```\n\nA functional stateless component would look like:\n\n```javascript\nvar Button = inject(\"color\")(\n    observer(({ color }) =\u003e {\n        /* ... etc ... */\n    })\n)\n```\n\n#### Customizing inject\n\nInstead of passing a list of store names, it is also possible to create a custom mapper function and pass it to inject.\nThe 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,\nthat are mapped into the original:\n\n`mapperFunction: (allStores, props, context) =\u003e additionalProps`\n\nSince version 4.0 the `mapperFunction` itself is tracked as well, so it is possible to do things like:\n\n```javascript\nconst NameDisplayer = ({ name }) =\u003e \u003ch1\u003e{name}\u003c/h1\u003e\n\nconst UserNameDisplayer = inject(stores =\u003e ({\n    name: stores.userStore.name\n}))(NameDisplayer)\n\nconst user = mobx.observable({\n    name: \"Noa\"\n})\n\nconst App = () =\u003e (\n    \u003cProvider userStore={user}\u003e\n        \u003cUserNameDisplayer /\u003e\n    \u003c/Provider\u003e\n)\n\nReactDOM.render(\u003cApp /\u003e, document.body)\n```\n\n_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_\n\n#### Using `PropTypes` and `defaultProps` and other static properties in combination with `inject`\n\nInject wraps a new component around the component you pass into it.\nThis means that assigning a static property to the resulting component, will be applied to the HoC, and not to the original component.\nSo if you take the following example:\n\n```javascript\nconst UserName = inject(\"userStore\")(({ userStore, bold }) =\u003e someRendering())\n\nUserName.propTypes = {\n    bold: PropTypes.boolean.isRequired,\n    userStore: PropTypes.object.isRequired // will always fail\n}\n```\n\nThe above propTypes are incorrect, `bold` needs to be provided by the caller of the `UserName` component and is checked by React.\nHowever, `userStore` does not need to be required! Although it is required for the original stateless function component, it is not\nrequired for the resulting inject component. After all, the whole point of that component is to provide that `userStore` itself.\n\nSo if you want to make assertions on the data that is being injected (either stores or data resulting from a mapper function), the propTypes\nshould be defined on the _wrapped_ component. Which is available through the static property `wrappedComponent` on the inject component:\n\n```javascript\nconst UserName = inject(\"userStore\")(({ userStore, bold }) =\u003e someRendering())\n\nUserName.propTypes = {\n    bold: PropTypes.boolean.isRequired // could be defined either here ...\n}\n\nUserName.wrappedComponent.propTypes = {\n    // ... or here\n    userStore: PropTypes.object.isRequired // correct\n}\n```\n\nThe same principle applies to `defaultProps` and other static React properties.\nNote that it is not allowed to redefine `contextTypes` on `inject` components (but is possible to define it on `wrappedComponent`)\n\nFinally, mobx-react will automatically move non React related static properties from wrappedComponent to the inject component so that all static fields are\nactually available to the outside world without needing `.wrappedComponent`.\n\n#### Strongly typing inject\n\n##### With TypeScript\n\n`inject` also accepts a function (`(allStores, nextProps, nextContext) =\u003e additionalProps`) that can be used to pick all the desired stores from the available stores like this.\nThe `additionalProps` will be merged into the original `nextProps` before being provided to the next component.\n\n```typescript\nimport { IUserStore } from \"myStore\"\n\n@inject(allStores =\u003e ({\n    userStore: allStores.userStore as IUserStore\n}))\nclass MyComponent extends React.Component\u003c{ userStore?: IUserStore; otherProp: number }, {}\u003e {\n    /* etc */\n}\n```\n\nMake sure to mark `userStore` as an optional property. It should not (necessarily) be passed in by parent components at all!\n\nNote: If you have strict null checking enabled, you could muffle the nullable type by using the `!` operator:\n\n```\npublic render() {\n   const {a, b} = this.store!\n   // ...\n}\n```\n\nBy [migrating to React Hooks](https://mobx-react.js.org/recipes-migration) you can avoid problems with TypeScript.\n\n#### Testing store injection\n\nIt 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.\n\nSo if you have in your app something like:\n\n```javascript\n\u003cProvider profile={profile}\u003e\n    \u003cPerson age={\"30\"} /\u003e\n\u003c/Provider\u003e\n```\n\nIn your test you can easily test the `Person` component by passing the necessary store as prop directly:\n\n```\nconst profile = new Profile()\nconst mountedComponent = mount(\n   \u003cPerson age={'30'} profile={profile} /\u003e\n)\n```\n\nBear in mind that using shallow rendering won't provide any useful results when testing injected components; only the injector will be rendered.\nTo test with shallow rendering, instantiate the `wrappedComponent` instead: `shallow(\u003cPerson.wrappedComponent /\u003e)`\n\n### disposeOnUnmount(componentInstance, propertyKey | function | function[])\n\nFunction (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.\n\n```javascript\nimport { disposeOnUnmount } from \"mobx-react\"\n\nclass SomeComponent extends React.Component {\n    // decorator version\n    @disposeOnUnmount\n    someReactionDisposer = reaction(...)\n\n    // decorator version with arrays\n    @disposeOnUnmount\n    someReactionDisposers = [\n        reaction(...),\n        reaction(...)\n    ]\n\n\n    // function version over properties\n    someReactionDisposer = disposeOnUnmount(this, reaction(...))\n\n    // function version inside methods\n    componentDidMount() {\n        // single function\n        disposeOnUnmount(this, reaction(...))\n\n        // or function array\n        disposeOnUnmount(this, [\n            reaction(...),\n            reaction(...)\n        ])\n    }\n}\n```\n\n## DevTools\n\n`mobx-react@6` and higher are no longer compatible with the mobx-react-devtools.\nThat is, the MobX react devtools will no longer show render timings or dependency trees of the component.\nThe reason is that the standard React devtools are also capable of highlighting re-rendering components.\nAnd the dependency tree of a component can now be inspected by the standard devtools as well, as shown in the image below:\n\n![hooks.png](hooks.png)\n\n## FAQ\n\n**Should I use `observer` for each component?**\n\nYou should use `observer` on every component that displays observable data.\nEven the small ones. `observer` allows components to render independently from their parent and in general this means that\nthe more you use `observer`, the better the performance become.\nThe overhead of `observer` itself is negligible.\nSee also [Do child components need `@observer`?](https://github.com/mobxjs/mobx/issues/101)\n\n**I see React warnings about `forceUpdate` / `setState` from React**\n\nThe following warning will appear if you trigger a re-rendering between instantiating and rendering a component:\n\n```\n\nWarning: forceUpdate(...): Cannot update during an existing state transition (such as within `render`). Render methods should be a pure function of props and state.`\n\n```\n\n-- or --\n\n```\n\nWarning: 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`.\n\n```\n\nUsually this means that (another) component is trying to modify observables used by this components in their `constructor` or `getInitialState` methods.\nThis violates the React Lifecycle, `componentWillMount` should be used instead if state needs to be modified before mounting.\n","funding_links":["https://opencollective.com/mobx"],"categories":["Code Design","react","MobileAPP","JavaScript","TypeScript","Uncategorized","Awesome MobX","目录"],"sub_categories":["Data Store","Uncategorized","Related projects and utilities","\u003ca id=\"state\"\u003e状态管理\u003c/a\u003e"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobxjs%2Fmobx-react","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmobxjs%2Fmobx-react","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmobxjs%2Fmobx-react/lists"}