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

About the developer

2.0K Stars 98 Forks MIT License 480 Commits 0 Opened issues


Lightweight React bindings for MobX based on React 16.8 and Hooks

Services available


Need anything else?

Contributors list


🚨🚨🚨 This repo has been moved to mobx

CircleCICoverage StatusNPM downloadsMinzipped size

TypeScriptcode style: prettier

Discuss on Github View changelog

This is a lighter version of mobx-react which supports React functional components only and as such makes the library slightly faster and smaller (only 1.5kB gzipped). Note however that it is possible to use

 inside the render of class components.
, it doesn't
, as
can be used instead.

Compatibility table (major versions)

| mobx | mobx-react-lite | Browser | | ---- | --------------- | ---------------------------------------------- | | 6 | 3 | Modern browsers (IE 11+ in compatibility mode) | | 5 | 2 | Modern browsers | | 4 | 2 | IE 11+, RN w/o Proxy support |

requires React 16.8 or higher.

User Guide 👉

API reference ⚒


(baseComponent: FunctionComponent

): FunctionComponent

The observer converts a component into a reactive component, which tracks which observables are used automatically and re-renders the component when one of these values changes. Can only be used for function components. For class component support see the



Is a React component, which applies observer to an anonymous region in your component.

 can be used both inside class and function components.

useLocalObservable(initializer: () => T, annotations?: AnnotationsMap): T

Creates an observable object with the given properties, methods and computed values.

Note that computed values cannot directly depend on non-observable values, but only on observable values, so it might be needed to sync properties into the observable using

(see the example below at

is a short-hand for:

const [state] = useState(() => observable(initializer(), annotations, { autoBind: true }))

enableStaticRendering(enable: true)


when running in an SSR environment, in which
wrapped components should never re-render, but cleanup after the first rendering automatically. Use
to inspect the current setting.

Deprecated APIs

useObserver(fn: () => T, baseComponentName = "observed", options?: IUseObserverOptions): T

This API is deprecated in 3.*. It is often used wrong (e.g. to select data rather than for rendering, and

better decouples the rendering from the component updates

interface IUseObserverOptions {
    // optional custom hook that should make a component re-render (or not) upon changes
    // Supported in 2.x only
    useForceUpdate: () => () => void

It allows you to use an observer like behaviour, but still allowing you to optimize the component in any way you want (e.g. using memo with a custom areEqual, using forwardRef, etc.) and to declare exactly the part that is observed (the render phase).

useLocalStore(initializer: () => T, source?: S): T

This API is deprecated in 3.*. Use

instead. They do roughly the same, but
accepts an set of annotations as second argument, rather than a
object. Using
is not recommended, see the deprecation message at
for details

Local observable state can be introduced by using the useLocalStore hook, that runs its initializer function once to create an observable store and keeps it around for a lifetime of a component.

The annotations are similar to the annotations that are passed in to MobX's

API, and can be used to override the automatic member inference of specific fields.

useAsObservableSource(source: T): T

The useAsObservableSource hook can be used to turn any set of values into an observable object that has a stable reference (the same object is returned every time from the hook).

This API is deprecated in 3.* as it relies on observables to be updated during rendering which is an anti-pattern. Instead, use

to synchronize non-observable values with values. Example:

// Before:
function Measurement({ unit }) {
    const observableProps = useAsObservableSource({ unit })
    const state = useLocalStore(() => ({
        length: 0,
        get lengthWithUnit() {
            // lengthWithUnit can only depend on observables, hence the above conversion with `useAsObservableSource`
            return observableProps.unit === "inch"
                ? `${this.length * 2.54} inch`
                : `${this.length} cm`

return <h1>{state.lengthWithUnit}</h1>


// After: function Measurement({ unit }) { const state = useLocalObservable(() => ({ unit, // the initial unit length: 0, get lengthWithUnit() { // lengthWithUnit can only depend on observables, hence the above conversion with useAsObservableSource return this.unit === "inch" ? ${this.length * 2.54} inch : ${this.length} cm } }))

useEffect(() =&gt; {
    // sync the unit from 'props' into the observable 'state'
    state.unit = unit
}, [unit])

return <h1>{state.lengthWithUnit}</h1>


Note that, at your own risk, it is also possible to not use

, but do
state.unit = unit
instead in the rendering. This is closer to the old behavior, but React will warn correctly about this if this would affect the rendering of other components.

Observer batching (deprecated)

Note: configuring observer batching is only needed when using

2.0.* or 2.1.*. From 2.2 onward it will be configured automatically based on the availability of react-dom / react-native packages

Check out the elaborate explanation.

In short without observer batching the React doesn't guarantee the order component rendering in some cases. We highly recommend that you configure batching to avoid these random surprises.

Import one of these before any React rendering is happening, typically

. For Jest tests you can utilize setupFilesAfterEnv.

React DOM:

import 'mobx-react-lite/batchingForReactDom'

React Native:

import 'mobx-react-lite/batchingForReactNative'


To opt-out from batching in some specific cases, simply import the following to silence the warning.

import 'mobx-react-lite/batchingOptOut'

Custom batched updates

Above imports are for a convenience to utilize standard versions of batching. If you for some reason have customized version of batched updates, you can do the following instead.

import { observerBatching } from "mobx-react-lite"


Running the full test suite now requires node 14+ But the library itself does not have this limitation

In order to avoid memory leaks due to aborted renders from React fiber handling or React

, on environments that does not support FinalizationRegistry, this library needs to run timers to tidy up the remains of the aborted renders.

This can cause issues with test frameworks such as Jest which require that timers be cleaned up before the tests can exit.



in the
of your tests to ensure that
cleans up immediately and allows tests to exit.

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.