---
url: /mobx-view-model/react/integration.md
---

# Integration with React

## Import path `mobx-view-model-react`

React integration APIs — [`withViewModel`](/react/api/with-view-model), [`withPropsViewModel`](/react/api/with-props-view-model), [`useCreateViewModel`](/react/api/use-create-view-model), [`useViewModel`](/react/api/use-view-model), [`ViewModelsProvider`](/react/api/view-models-provider), [`OnlyViewModel`](/react/api/only-view-model), 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`**:

```ts
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](/api/view-models/interface) should be connected to a React view component.\
To achieve this you can use:

* [`withViewModel()` HOC](/react/api/with-view-model) - recommended way
* [`withPropsViewModel()` HOC](/react/api/with-props-view-model) - same as `withViewModel`, but all component props become `payload` (no `payload` prop)
* [`useCreateViewModel()` hook](/react/api/use-create-view-model) - simplest way, more performant in many cases

## 2. Render in React tree

#### use [withViewModel() HOC](/react/api/with-view-model)

Then you should render the component returned from this function

```tsx
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](/react/api/use-create-view-model)

Then you should render your React components using this hook

```tsx
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](/api/view-model-store/interface)

[ViewModelStore](/api/view-model-store/interface) 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`](/react/api/view-models-provider) Context Provider.

```tsx
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()`](/react/api/use-view-model) to look up registered view models by class, component, or ID.

::: tip [`isMounted`](/api/view-models/interface#ismounted-boolean) state\
This state is based on calling the [`mount()` method](/api/view-models/interface#mount-void-promise-void). On the client, [`useCreateViewModel()`](/react/api/use-create-view-model) 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`](/react/api/with-view-model): use its [`fallback`](/react/api/with-view-model#fallback) while `isMounted` is `false` (CSR / when the hook is not suspending).
* With direct [`useCreateViewModel`](/react/api/use-create-view-model): there is no `fallback` option — gate the UI on `model.isMounted` yourself (or wrap the tree in [`Suspense`](https://react.dev/reference/react/Suspense) when [`viewModelsConfig.mode = 'ssr'`](/api/view-models/view-models-config#mode) on React 19+, where the hook waits via `use()`).
  :::

::: warning Do not call [`mount()`](/api/view-models/interface#mount-void-promise-void) / [`unmount()`](/api/view-models/interface#unmount-void) 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()`](/api/view-model-store/interface#unmount-instance).
:::