> This page is for version v2024-01-31.
> For other versions, use one of these documentation indexes:
> - v2024-05-25 (default): https://docs.monite.com/v-2024-05-25/llms.txt
> - v2024-01-31: https://docs.monite.com/v2024-01-31/llms.txt
> - v2023-09-01: https://docs.monite.com/v2023-09-01/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.monite.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.monite.com/_mcp/server.

# Monite React SDK v4 migration guide

## Overview

This guide provides step-by-step instructions on migrating to the latest version of the [Monite React SDK](./index).
Please read carefully and ensure all steps are followed to avoid potential issues.

## Upgrade steps

#### Review the changelog

Check the [Monite SDK changelog](https://github.com/team-monite/monite-sdk/releases) for the breaking changes and deprecated methods.

#### Uninstall old dependencies

The `@monite/sdk-api` package has been deprecated.
All API calls are now part of the main `@monite/sdk-react` package.

You will need to uninstall the deprecated package and update the imports.

**`npm`**

```sh title="npm" for="npm"
npm uninstall @monite/sdk-api
```

**`Yarn`**

```sh title="Yarn" for="Yarn"
yarn remove @monite/sdk-api
```

#### Update the imports

Replace any usages of `@monite/sdk-api` with `@monite/sdk-react` in your code.

```diff
- import { ... } from '@monite/sdk-api';
+ import { ... } from '@monite/sdk-react';
```

#### Update the package

**`npm`**

```sh title="npm" for="npm"
npm install @monite/sdk-react@latest
```

**`Yarn`**

```sh title="Yarn" for="Yarn"
yarn add @monite/sdk-react@latest
```

#### Replace deprecated methods

If your code uses deprecated methods, replace them with the new recommended alternatives as detailed in the [changelog](https://github.com/team-monite/monite-sdk/releases).

#### Test thoroughly

After making the necessary code changes, test that the Monite SDK works correctly within your application.

## New `MoniteProvider` syntax

The `@monite/sdk-api` package has been deprecated.
All API calls are now part of the main `@monite/sdk-react` package.

Also, the `MoniteSDK` object that was used to initialize the `MoniteProvider` has been removed.
The [`MoniteProvider.monite`](./components/index#the-moniteprovider-wrapper) prop now expects a plain JavaScript object instead of a `MoniteSDK` instance.

The following example shows the old and new syntaxes.

#### New SDK v4 syntax

```js
import { MoniteProvider } from "@monite/sdk-react";

const monite = {
  apiUrl: "https://api.sandbox.monite.com/v1",
  entityId: "ENTITY_ID",
  fetchToken: fetchToken,
};

function App() {
  return (
    <div className="App">
      <MoniteProvider monite={monite}>
        ...
      </MoniteProvider>
    </div>
  );
}

export default App;
```

#### Old SDK v3 syntax

```js
import { MoniteSDK } from "@monite/sdk-api";
import { MoniteProvider } from "@monite/sdk-react";

const monite = new MoniteSDK({
  apiUrl: "https://api.sandbox.monite.com/v1",
  entityId: "ENTITY_ID",
  fetchToken: fetchToken,
});

function App() {
  return (
    <div className="App">
      <MoniteProvider monite={monite}>
        ...
      </MoniteProvider>
    </div>
  );
}

export default App;
```

## Theming update

### Key changes

* **No more Material UI.** The new theme object is a custom solution and no longer uses the Material UI theme specification.
* **`palette` is now `colors`.** The `palette` object has been replaced by a flatter `colors` object.
  Color definitions are now a single string value instead of an object with `main` and `contrastText`.
* **New top-level properties.** `borderRadius` and `spacing` have been added to control general UI metrics.
* **Simplified typography.** Typography variants have been standardized, and values are now primarily numbers instead of strings.

### Migration steps

Follow these steps to convert your old `customTheme` object to the new format.

#### 1. Update color definitions (`palette` → `colors`)

The `palette` object is now `colors`.
You'll need to map your old color values to the new, simplified keys:

* Take the `main` value from your old color objects (e.g. `palette.primary.main`).
* Assign this string directly to the new color key (e.g. `colors.primary`).

#### New theme structure in SDK v4

```ts
const newTheme = {
  colors: {
    primary: "#42a5f5",      // from palette.primary.main
    background: "#e3f2fd",   // from palette.background.paper
    text: "#000",            // from palette.text.primary
    // secondary, neutral, info, etc. would be added here if needed
  },
};
```

#### Old theme structure in SDK v3

```ts
const oldTheme = {
  palette: {
    mode: "light",
    primary: {
      main: "#42a5f5",
      contrastText: "#fff",
    },
    background: {
      paper: "#e3f2fd",
    },
    text: {
      primary: "#000",
    },
  },
};
```

#### 2. Update typography

The `typography` object is similar but has key differences in its variants and value types.

* **Value types**: `fontSize` and `fontWeight` should now be numbers, not strings (e.g. `500` not `"500"`).
  `lineHeight` remains a string with a `px` unit.
* **Variant names**: Some variants like `button` have been removed in favor of more semantic names like `body1` or `body2`.
  You'll need to map your old styles to the most appropriate new variant.

#### New typography in SDK v4

```ts
const newTypography = {
  fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace", // remains the same
  fontSize: 16, // Add a base font size
  h2: {
    fontSize: 26,       // Changed to number
    fontWeight: 500,    // Changed to number
    lineHeight: '32px', // Add a line-height
  },
  // 'button' is deprecated. Apply styles to 'body1' or another variant instead.
  body1: {
    fontSize: 16,
    fontWeight: 500, // Matched from 'button' (fontWeight '300' in old example was likely a typo)
    lineHeight: '24px',
    // 'textTransform' is no longer a theme option.
  },
};
```

#### Old typography in SDK v3

```ts
const oldTypography = {
  fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace",
  h2: {
    fontSize: "26px",
    fontWeight: "500",
  },
  button: {
    fontSize: "16px",
    textTransform: "uppercase",
  },
};
```

#### 3. Add new global properties

Add the new `borderRadius` and `spacing` properties at the top level of your theme object.
You can use the default values to start.

```js
const newTheme = {
  borderRadius: 6,
  spacing: 8,
  colors: { ... },
  typography: { ... },
};
```

### ❌ Unsupported & deprecated properties

The following properties from the old Material UI theme are no longer supported:

* `palette.mode`: The light/dark mode toggle is not supported anymore.
* `palette.*.contrastText`: The new `colors` object does not have a field for contrasting text color. This is now handled internally.
* `palette.background.paper`: This is simplified to `colors.background`.
* `palette.text.secondary`: This is simplified to `colors.text`.
* `typography.button`: This variant has been removed. Use `body1` or `body2` instead.
* `typography.*.textTransform`: This CSS property can no longer be configured through the theme.

### Complete theme migration example

Here is a full conversion of the sample `customTheme` from the old format to the new format.

#### SDK v4 (new)

```js
const customTheme = {
  // 1. Add new global properties
  borderRadius: 6,
  spacing: 8,

  // 2. Convert 'palette' to 'colors'
  colors: {
    primary: '#42a5f5',
    success: '#1fb42b',
    background: '#e3f2fd',
    text: '#000',
    // Fill in other colors or use defaults
    secondary: '#707070',
    neutral: '#707070',
    info: '#3737FF',
    error: '#CC394B',
  },

  // 3. Update typography
  typography: {
    fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace",
    fontSize: 16, // Set a base font size
    h2: {
      fontSize: 26,       // Converted to number
      fontWeight: 500,    // Converted to number
      lineHeight: '32px', // Add required line-height
    },
    h3: {
      fontSize: 24,       // Using default size
      fontWeight: 600,    // Using default weight
      lineHeight: '32px', // Approximate from old 1.13 ratio
    },
    // The 'button' and 'textTransform' properties are removed.
    // Apply relevant styles to a new variant like 'body1'.
    body1: {
      fontSize: 16,
      fontWeight: 400, // Default weight
      lineHeight: '24px',
    },
  }
};
```

#### SDK v3 (old)

```js
const customTheme = {
  palette: {
    mode: "light",
    primary: {
      main: "#42a5f5",
      contrastText: "#fff",
    },
    background: {
      paper: "#e3f2fd",
    },
    text: {
      primary: "#000",
      secondary: "#000",
    },
    success: {
      main: "#1fb42b",
      contrastText: "#fff"
    },
  },
  typography: {
    fontFamily: "Comic Sans MS, Comic Sans, cursive, monospace",
    h2: {
      fontSize: "26px",
      fontWeight: "500",
    },
    h3: {
      lineHeight: 1.13,
    },
    button: {
      fontSize: "16px",
      fontWeight: "300",
      textTransform: "uppercase",
    },
  },
};
```

## Troubleshooting

If you encounter any issues during or after the migration, refer to the full [Monite SDK documentation](./index) for usage tips and FAQs.

## Support

For further assistance, [contact our support team](../../intro/support).