/mobx-react-lite

Lightweight React bindings for MobX based on React 16.8 and Hooks

Primary LanguageTypeScriptMIT LicenseMIT

mobx-react-lite

CircleCICoverage StatusNPM downloadsMinzipped size

TypeScriptcode style: prettier

Join the chat at https://gitter.im/mobxjs/mobx

NPM

You need React version 16.8.0 and above

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). In fact mobx-react@6 has this library as a dependency and builds on top of it.

The library does not include any Provider/inject utilities as they can be fully replaced with React Context. Check out the migration guide.

Class based components are not supported except using <Observer> directly in class render method. If you want to transition existing projects from classes to hooks, use mobx-react 6+.

See more at the libraries overview.

User Guide 👉 https://mobx-react.js.org

The site contains various examples and recipes for using MobX in React world. Feel free to contribute. The API reference of this package follows 👇.

API reference ⚒

<Observer>{renderFn}</Observer> (user guide)

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

observer<P>(baseComponent: FunctionComponent<P>, options?: IObserverOptions): FunctionComponent<P> (user guide)

interface IObserverOptions {
    // Pass true to wrap the inner component with React.forwardRef.
    // It's false by the default.
    forwardRef?: boolean
}

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.

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

interface IUseObserverOptions {
    // optional custom hook that should make a component re-render (or not) upon changes
    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<T, S>(initializer: () => T, source?: S): T (user guide)

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.

useAsObservableSource<T>(source: T): T (user guide)

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).

Observer batching

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 index.js/ts. For Jest tests you can utilize setupFilesAfterEnv.

React DOM:

import 'mobx-react-lite/batchingForReactDom'

React Native:

import 'mobx-react-lite/batchingForReactNative'

Opt-out

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"
observerBatching(customBatchedUpdates)