Beyond JSX

Note: This section requires knowledge about the low level apis for creating elements, such as React.createElement or ReactDOM.createDOMElementVariadic.

Note: The output shown for the examples on this page assumes your rescript.json to be set to "jsx": { "version": 4, "mode": "classic" }. We will update it for automatic mode soon.

Component Types

A plain React component is defined as a ('props) => React.element function. You can also express a component more efficiently with our shorthand type React.component<'props>.

Here are some examples on how to define your own component types (often useful when interoping with existing JS code, or passing around components):

RES
// Plain function type
type friend = {name: string, online: bool}
type friendComp = friend => React.element

// Equivalent to
// ({padding: string, children: React.element}) => React.element
type props = {padding: string, children: React.element}
type containerComp = React.component<props>

The types above are pretty low level (basically the JS representation of a React component), but since ReScript React has its own ways of defining React components in a more language specific way, let's have a closer look on the anatomy of such a construct.

JSX Component Interface

A ReScript React component needs to be a (sub-)module with a make function and props type to be usable in JSX. To make things easier, we provide a @react.component decorator to create those functions for you:

module Friend = {
  @react.component
  let make = (~name: string, ~children) => {
    <div>
      {React.string(name)}
      children
    </div>
  }
}

In the expanded output:

• props: A generated record type that has fields according to the labeled arguments of the make function

• make: A converted make function that complies to the component interface (props) => React.element

Special Case React.forwardRef

The @react.component decorator also works for React.forwardRef calls:

module FancyInput = {
  @react.component
  let make = React.forwardRef((~className=?, ~children, ref) =>
    <div>
      // use ref here
    </div>
  )
}

As shown in the expanded output above, our decorator desugars the function passed to React.forwardRef in the same manner as a typical component make function. It also creates a props type with an optional ref field, so we can use it in our JSX call (<FancyInput ref=.../>).

So now that we know how the ReScript React component transformation works, let's have a look on how ReScript transforms our JSX constructs.

JSX Under the Hood

Whenever we are using JSX with a custom component ("capitalized JSX"), we are actually using React.createElement to create a new element. Here is an example of a React component without children:

<Friend name="Fred" age=20 />

As you can see, it uses Friend.make to call the React.createElement API. In case you are providing children, it will use React.createElementVariadic instead (which is just a different binding for React.createElement):

<Container width=200>
  {React.string("Hello")}
  {React.string("World")}
</Container>

Note that the children: React.null field has no relevance since React will only care about the children array passed as a third argument.

Dom Elements

"Uncapitalized JSX" expressions are treated as DOM elements and will be converted to ReactDOM.createDOMElementVariadic calls:

<div title="test"/>

The same goes for uncapitalized JSX with children:

<div title="test">
  <span/>
</div>