Skip to content

RoactCompat

The RoactCompat package is designed to have the same interface as legacy Roact. This should allow easier adoption of Roact 17 in existing Roact code.

RoactCompat is fully compatible with all Roact 17 logic. In particular, you may wish to use RoactCompat in combination with the React and ReactRoblox packages that provide the new interface.

Caution

RoactCompat is not compatible with legacy Roact in any way. It should be used only as a drop-in replacement for legacy Roact, for the purposes of upgrading existing projects written for legacy Roact.

RoactCompat.Component

Re-exports React.Component.

RoactCompat.PureComponent

Re-exports React.PureComponent.

RoactCompat.createElement

Re-exports React.createElement.

RoactCompat.createContext

Re-exports React.createContext.

RoactCompat.createRef

Re-exports React.createRef.

RoactCompat.forwardRef

Re-exports React.forwardRef.

RoactCompat.mount

RoactCompat.mount(
    element: ReactElement,
    container: Instance?,
    name: string?
): RoactTree
Compatibility method mimicking legacy Roact.mount.

For all intents and purposes, this should function equivalently to legacy Roact's mount function. Under the hood, RoactCompat takes the following steps:

  1. Creates a root using React.createRoot
  2. Calls root:render with the provided element
    • React's roots take complete control of the provided container, deleting all existing children. Legacy Roact does not tamper with existing children of the provided container. To mimic the legacy behavior, we use a Portal to mount into the container instead of providing it directly to the root.
    • When _G.__ROACT_17_INLINE_ACT__ is enabled, the render call is automatically wrapped in ReactRoblox.act to ensure that mounting behavior resolves synchronously in tests.
  3. Returns an opaque handle to the root that can be used with RoactCompat.update and RoactCompat.unmount

RoactCompat.update

RoactCompat.update(tree: RoactTree, element: ReactElement): RoactTree
Compatibility method mimicking legacy Roact.update.

The first argument should be the value returned from a prior call to RoactCompat.mount or RoactCompat.update. This function will not work if the argument passed in was created with legacy Roact.

RoactCompat.unmount

RoactCompat.unmount(tree: RoactTreeHandle)
Compatibility method mimicking legacy Roact.unmount.

-- API compatibility layers to accommodate old interfaces

RoactCompat.createFragment

RoactCompat.createFragment(elements: { [string | number]: ReactElement }): ReactElement
Compatibility method mimicking Roact.createFragment. Uses the special component React.Fragment under the hood.

RoactCompat.oneChild

RoactCompat.oneChild(
    children: { [string | number]: ReactElement } | ReactElement | nil
): ReactElement
Compatibility method mimicking Roact.oneChild. This function is similar to React.Children.only, but provides additional functionality to unwrap a table that may contain a single element.

RoactCompat.setGlobalConfig

RoactCompat.setGlobalConfig(configValues: { [string]: boolean })
Compatibility method mimicking Roact.setGlobalConfig. This does not apply to Roact 17, so calling this function is a no-op.

Info

If you need to apply global configuration to Roact 17, you can do so by setting global values FIXME LINK TO CONFIGURATION DOC

RoactCompat.Portal

Compatibility component mimicking Roact.Portal. Uses the React.createPortal function under the hood.

RoactCompat.Ref

Compatibility field that mimics the special symbol key Roact.Ref. In RoactCompat, the Ref field is simply equal to the string "ref", which is a reserved prop key in Roact 17.

This allows prop tables that are written for legacy Roact: 

Roact.createElement("TextLabel", {
    Text = "Hello",
    [Roact.Ref] = textLabelRef,
})
...to be equivalent to prop tables written for Roact 17, which uses "ref" as a reserved prop name: 
Roact.createElement("TextLabel", {
    Text = "Hello",
    ref = textLabelRef,
})

RoactCompat.Children

Compatibility field that mimics the special symbol key Roact.Children. In RoactCompat, the Children field is simply equal to the string "children", which is a reserved prop key in Roact 17.

This allows prop tables that are written for legacy Roact: 

-- forwards the children provided to this component
Roact.createElement("Frame", nil, self.props[Roact.Children])
...to be equivalent to prop tables written for Roact 17, which uses "children" as a reserved prop name: 
-- forwards the children provided to this component
Roact.createElement("Frame", nil, self.props.children)

Caution

This is not to be confused with React.Children, which is a set of utilities for transforming or interacting with sets of children passed to createElement.

RoactCompat.None

Re-exports React.None.

RoactCompat.Event

Re-exports React.Event.

RoactCompat.Change

Re-exports React.Change.

RoactCompat.createBinding

Re-exports ReactRoblox.createBinding.

RoactCompat.joinBindings

Re-exports ReactRoblox.joinBindings.

RoactCompat.act

Re-exports ReactRoblox.act.