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:

Creates a root using React.createRoot
- When _G.__ROACT_17_COMPAT_LEGACY_ROOT__ is enabled, this will use React.createLegacyRoot instead
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.
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.