Roact Visualizer
A plugin for the visualization and real-time development of Roact trees.
Overview
(Optional) What is Roact?
Roact is a declarative UI library similar to React. It is an open source project that is also currently officially supported by and upkept by Roblox internal engineers. To learn more about Roact, I would recommend viewing its documentation.
Roact allows you to create reusable UI elements entirely through code - this plugin exists to turn that code into visible UI elements in real-time as you work!
Tired of entering Play Solo every time you want to test a slight change when working on a Roact component? Roact Visualizer is designed to cut down on development time by providing a live preview window for your Roact elements that can even update in real-time as you work.
This plugin is designed to work with any version of Roact that your project may be using. This includes old versions and even private forks, as long as they contain the basic functionality of creating and mounting components.
Pictured is a TextBox Roact component being previewed inside the Roact Visualizer plugin. This plugin supports both Light and Dark theme.
Getting Started
Installation
- Visit the plugin’s details page and purchase it to install it. Alternatively, you can install the plugin directly from the Toolbox in Studio, or if you have Rojo, you can build the plugin from its source and create a local version for yourself.
- After installing and opening the plugin, open Studio and navigate to the Plugins → Manage Plugins interface. From here, you can grant the “script injection” permissions to the plugin. Do not grant these permissions to plugins you do not trust. Make sure you have a legitimate copy of the plugin before doing this! A legitimate copy can only be obtained via purchasing the plugin or building it from source.
- After granting the necessary permissions, close and reopen the plugin to begin using it.
Locating Roact
After opening the plugin, it will prompt you to locate your local Roact install. This should point to the top-level ModuleScript named “Roact” - the same one that your component’s scripts require in order to access the Roact API. In most cases, this will be as simple as clicking “Auto Detect”. Once you have notified Roact Visualizer about your Roact install’s location, you won’t have to do so again for that place unless you move it.
The Interface
The core workflow of the Roact Visualizer is simply selecting the ModuleScript associated with whatever Roact component in your project you wish to visualize, then clicking Update as you work to instantly see how your script changes translate to the outputted UI elements.
In this video, I am editing a component’s script. I click the plugin to start looking for a component to visualize, and it auto-detects that I have a script open. I can then select the currently opened script, and it immediately renders the component inside the plugin.
In this video, I make a change to the component, then click Update. The viewport updates immediately to reflect my change.
Below you can see an overview of the purpose of each button in the plugin’s window:
Show Image
Show Details
- Update: Click to update the component in the view window to reflect the latest changes to the component itself, its props, and/or the tree. If Auto Update is enabled, this button will be replaced with an Auto indicator.
- Tree: Left click to open the Tree script (more details below). Right click to access more options.
- Props: Same as Tree, but for the Props script.
- Align: Click to toggle between centering the view or using the component’s actual position.
- Settings: Click to access Auto Update and additional settings.
- New: Click to open a new component for previewing.
- Open Script: Click to open the current component’s script in the script editor.
- Current Component: Displays the name of the current component being previewed.
- Close Component: Closes the display of the current component.
- About: Access information about the plugin and acquire a link to this forum post.
Auto Update
Auto Update can be toggled in the plugin’s settings menu. It allows you to see the effects of your script changes in real-time as you modify them.
In this video, I enable Auto Update in the settings menu. Then, when I make a change to the component’s script, the viewport updates automatically without any other inputs from me. Convenient!
- When Auto Update is off, you will have to manually click the Update button to see the script changes. This can be very useful when making large, sweeping changes to a component.
- When Auto Update is on, the script changes will be shown immediately after you stop typing for a short delay.
- The Auto Update delay can be adjusted in the settings. A shorter delay is more responsive, but can be laggier in large projects and will lead to more syntax error warnings as the scripts try to reload even if you haven’t completed a line of code.
Props and Tree
The Props and Tree buttons in the plugin allow you to open and modify two special inputs to the view window, which make the plugin highly customizable and able to visualize practically any Roact component you desire.In this video, I click the Props button to open the props script, then modify it to return a value for the prop at “Text”. My component receives a prop named “Text”, so the view updates to reflect this change.
In this video, I right-click the Tree button to open the extra options menu, then load the preset tree “Send to New Window”. After the view updates, the tree is now sending the component to a new PluginGui, which I can drag and resize on its own.
- The Tree script returns a Roact component, which ultimately is what is visualized within the plugin’s viewport. As part of this tree, the component you selected to visualize is returned as an element. The default Tree simply returns the element and does nothing more. However, you can use this script to create context providers, portals to other UI containers, state changes, and any other items necessary to the functioning of your previewed component.
- The Props script returns a table which will be sent to the Tree component’s props. The default Tree component simply passes these props on to the component being visualized.
- Both the Tree and Props buttons can be right clicked to access a menu containing additional options. These menus allow you to save and load the scripts to the place for later access, as well as load packaged presets.
- Currently, the plugin comes with two preset Tree scripts, which allow the previewed component to be retargeted to the 3D view and to a separate PluginGui, respectively. It also comes with two presets that support both Horsecat and Hoarcekat-style stories.