Integration with React

Import path mobx-view-model-react

React integration APIs — withViewModel, withPropsViewModel, useCreateViewModel, useViewModel, ViewModelsProvider, OnlyViewModel, and related types such as ViewModelProps — are published in the separate mobx-view-model-react package.

Keep importing view-model classes, stores, and global configuration from mobx-view-model:

import { ViewModelBase, ViewModelStoreBase, viewModelsConfig } from "mobx-view-model";
import { withViewModel, type ViewModelProps } from "mobx-view-model-react";

The mobx-view-model-react package contains React integration APIs; mobx-view-model contains the core view-model classes, stores, and configuration.

Integration consists of 2-3 steps.

1. Connect ViewModel with View

Your ViewModel should be connected to a React view component.
To achieve this you can use:

• withViewModel() HOC - recommended way
• withPropsViewModel() HOC - same as withViewModel, but all component props become payload (no payload prop)
• useCreateViewModel() hook - simplest way, more performant in many cases

2. Render in React tree

use withViewModel() HOC

Then you should render the component returned from this function

import { ViewModelBase } from "mobx-view-model";
import { withViewModel, type ViewModelProps } from "mobx-view-model-react";

class YourComponentVM extends ViewModelBase {}

export interface YourComponentProps extends ViewModelProps<YourComponentVM> {
  yourProp?: string;
}

const YourComponent = withViewModel(
  YourComponentVM,
  ({ model, yourProp }: YourComponentProps) => {
    return <div>{model.id} {yourProp}</div>;
  },
);

const YourApp = () => {
  return (
    <YourComponent yourProp="hi v11" />
  )
}

use useCreateViewModel() hook

Then you should render your React components using this hook

import { ViewModelBase } from "mobx-view-model";
import { useCreateViewModel } from "mobx-view-model-react";
import { observer } from "mobx-react-lite";

class YourComponentVM extends ViewModelBase {}

const YourComponent = observer(() => {
  const model = useCreateViewModel(YourComponentVM);

  return (
    <div>
      {model.id}
    </div>
  )
})

const YourApp = () => {
  return (
    <YourComponent />
  )
}

3. [Optional] Use ViewModelStore

ViewModelStore is a powerful tool that allows you to look up and access your view model instances anywhere.
To use this store:

1. Create instance of ViewModelStore
2. Wrap your application into ViewModelsProvider Context Provider.

import { ViewModelStoreBase } from "mobx-view-model";
import { ViewModelsProvider } from "mobx-view-model-react";

const vmStore = new ViewModelStoreBase();

const YourApp = () => {
  return (
    <ViewModelsProvider value={vmStore}>
      ...
    </ViewModelsProvider>
  )
}

With this step you can use useViewModel() to look up registered view models by class, component, or ID.

isMounted state

This state is based on calling the mount() method. On the client, useCreateViewModel() runs it in a commit effect after connecting a store-backed ViewModel. During SSR it runs during render. On the client, the initial render can see isMounted === false; the component re-renders after synchronous or asynchronous mounting completes.

• With withViewModel: use its fallback while isMounted is false (CSR / when the hook is not suspending).
• With direct useCreateViewModel: there is no fallback option — gate the UI on model.isMounted yourself (or wrap the tree in Suspense when viewModelsConfig.mode = 'ssr' on React 19+, where the hook waits via use()).

Do not call mount() / unmount() manually

On the client, useCreateViewModel calls mount() in its commit effect; during SSR it handles the lifecycle while rendering. When a store is present, connect() registers the instance but does not mount it; the hook delegates unmounting to the store's unmount().