---
title: Migrate from JSX v3
description: "Migrate from JSX v3"
canonical: "/docs/react/latest/migrate-react"
---

# Migrate from JSX v3

JSX v4 introduces a new idiomatic record-based representation of components which is incompatible with v3. Because of this, either the entire project or dependencies need to be compiled in v4 mode, or some compatibility features need to be used to mix v3 and v4 in the same project. This page describes how to migrate from v3 to v4.

## Configuration

Remove the existing JSX configuration from `rescript.json`:

```json
{
  "reason": { "react-jsx": 3 }
}
```

Then add the new JSX configuration:

```json
{
  "jsx": { "version": 4 }
}
```

or, to keep using the legacy `React.createElement` API like with JSX v3:

```json
{
  "jsx": { "version": 4, "mode": "classic" }
}
```

### File-level config

The top-level attribute `@@jsxConfig` is used to update the `jsx` config for the rest of the file (or until the next config update). Only the values mentioned are updated, the others are left unchanged.

```res
@@jsxConfig({ version: 4, mode: "automatic" })

module Wrapper = {
  module R1 = {
    @react.component  // V4 and new _jsx transform
    let make = () => body
  }

  @@jsxConfig({ version: 4, mode: "classic" })

  module R2 = {
    @react.component  // V4 with `React.createElement`
    let make = () => body
  }
}

@@jsxConfig({ version: 3 })

@react.component  // V3
let make = () => body
```

### v3 compatible mode

JSX v3 is still available with the latest version of compiler and rescript-react.

```json
{
  "jsx": { "version": 3, "v3-dependencies": ["rescript-relay"] },
  "bsc-flags": ["-open ReactV3"]
}
```

To build certain dependencies in v3 compatibility mode, whatever the version used in the root project, use `"v3-dependencies"`. The listed dependencies will be built-in v3 mode, and in addition `-open ReactV3` is added to the compiler options.

## Migration of v3 components

Some components in existing projects are written in a way that is dependent on the v3 internal representation. Here are a few examples of how to convert them to v4.

### `makeProps` does not exist in v4

Rewrite this:

```res
// V3
module M = {
  @obj external makeProps: (~msg: 'msg, ~key: string=?, unit) => {"msg": 'msg} = ""

  let make = (~msg) => <div> {React.string(msg)} </div>
}
```

To this:

```res example
// V4
module M = {
  type props<'msg> = {msg: 'msg}
  let make = props => <div> {React.string(props.msg)} </div>
}
```

### React.Context

Rewrite this:

```res
module Context = {
  let context = React.createContext(() => ())

  module Provider = {
    let provider = React.Context.provider(context)

    @react.component
    let make = (~value, ~children) => {
      React.createElement(provider, {"value": value, "children": children}) // Error
    }
  }
}
```

To this:

```res example
module Context = {
  let context = React.createContext(() => ())

  module Provider = {
    let make = React.Context.provider(context)
  }
}
```

### React.forwardRef (Discouraged)

Rewrite this:

```res
module FancyInput = {
  @react.component
  let make = React.forwardRef((
    ~className=?,
    ~children,
    ref_, // argument
  ) =>
    <div>
      <input
        type_="text"
        ?className
        ref=?{ref_->Nullable.toOption->Option.map(ReactDOM.Ref.domRef)}
      />
      children
    </div>
  )
}

@react.component
let make = (~onClick) => {
  let input = React.useRef(Nullable.null)

  <div>
    <FancyInput ref=input> // prop
      <button onClick> {React.string("Click to focus")} </button>
    </FancyInput>
  </div>
}
```

To this: In v3, there is an inconsistency between `ref` as prop and `ref_` as argument. With JSX v4, `ref` is only allowed as an argument.

```res example
module FancyInput = {
  @react.component
  let make = React.forwardRef((
    ~className=?,
    ~children,
    ref, // only `ref` is allowed
  ) =>
    <div>
      <input
        type_="text"
        ?className
        ref=?{ref->Nullable.toOption->Option.map(ReactDOM.Ref.domRef)}
      />
      children
    </div>
  )
}

@react.component
let make = (~onClick) => {
  let input = React.useRef(Nullable.null)

  <div>
    <FancyInput ref=input>
      <button onClick> {React.string("Click to focus")} </button>
    </FancyInput>
  </div>
}
```

### Mangling the prop name

The prop name was mangled automatically in v3, such as `_open` becomes `open` in the generated js code. This is no longer the case in v4 because the internal representation is changed to the record instead object. If you need to mangle the prop name, you can use the `@as` annotation.

Rewrite this:

```res
module Comp = {
  @react.component
  let make = (~_open, ~_type) =>
    <Modal _open _type>
      <Description />
    </Modal>
}
```

To this:

```res
module Comp = {
  @react.component
  let make =
    (@as("open") ~_open, @as("type") ~_type) =>
      <Modal _open _type>
        <Description />
      </Modal>
}
```

### Bindings to JS components with optional props

Previously, you could wrap optional props with an explicit `option` when writing bindings to JS components. This approach functioned only due to an implementation detail of the ppx in JSX 3; it's not how to correctly write bindings to a function with optional arguments.

Rewrite this:

```res
module Button = {
  @module("./Button") @react.component
  external make: (~text: option<string>=?) => React.element = "default"
}
```

To this:

```res example
module Button = {
  @module("./Button") @react.component
  external make: (~text: string=?) => React.element = "default"
}
```