Build custom React components
Learn how to develop and deploy custom React components for Retool apps.
Custom components libraries is distinct from the legacy custom component feature. Retool does not recommend creating custom components using the legacy feature.
If Retool's built-in components don't work for your use case, you can build custom components in React. Custom components can leverage public or private npm packages, as they are written locally in your development environment and then deployed to Retool. After deploying, you can drag and drop components into apps as you would any other component.
To allow custom components to interact with your Retool app, Retool provides a TypeScript API. This API lets you define events that trigger event handlers and add properties to the Inspector for your component.
Custom components are contained within libraries, and each library has a unique name. Custom components deployed to Retool are automatically shown in the Component Library, in a section that matches the library's label.
Prerequisites
To build a custom component library, you need:
- Node.js v20 or later installed in your development environment.
- Admin permissions in Retool.
- [Optional] If you are running self-hosted Retool, setting the
ALLOW_SAME_ORIGIN_OPTION
, andSANDBOX_DOMAIN
environment variables is recommended.
The following steps guide you through the development flow to create and use a custom component. The example component contains a Name property and displays a message with the provided name. The code will look something like this:
export const HelloWorldComponent: FC = () => {
// Allows the builder to specify a "name" property on each component they build with.
// The builder can then pass data from their Retool app into the component by setting a value
// for the "name" property.
const [name, setName] = Retool.useStateString({
name: "name",
});
return (
<div>
<div>Hello {name}!</div>
</div>
);
};
After building the component, you can drag it to the canvas like any other component.
1. Clone the template repository
Clone the custom-component-collection-template GitHub repository.
- HTTPS
- SSH
git clone https://github.com/tryretool/custom-component-collection-template new-custom-component
git clone git@github.com:tryretool/custom-component-collection-template.git new-custom-component
2. Install dependencies
Change your directory to new-custom-component
and run:
npm install
It's possible to use almost any npm
packages that support being run in the browser, including from private npm
repositories.
3. Log in to Retool
Log in using the following command. You need to provide an API access token with read and write scopes for Custom Component Libraries. See the Retool API authentication documentation for instructions on generating an access token.
npx retool-ccl login
4. Create a component library
Create a component library for your component.
npx retool-ccl init
This command guides you through picking a name and description for your library. It then adds those and other metadata to your local package.json
file and calls Retool to construct the library.
5. Rename your component
Rename the HelloWorld
component as needed. All components exported from src/index.tsx
are synced to Retool.
6. Start dev mode
Use dev mode to test changes as you build your component:
npx retool-ccl dev
This syncs changes to Retool every time you change a file. You can then test component changes in any Retool app.
7. Add components to the canvas
Select the custom component from the Add components panel, and drag it into your app. The name of the custom component is the same as the name of your exported React component. The component is displayed in a section titled with the label of your library. You may need to refresh the page for new components to show up in the Add components panel.
8. Develop your component
Write code for your component in your preferred editor. See the TypeScript API section for more information about how to develop your component.
9. Deploy your component
When you're done creating your component, deploy it with the following command:
npx retool-ccl deploy
This pushes an immutable version of the component to Retool.
Now your component library is ready for production use. If you want to use your component library in public apps, then you need to go to Settings > Custom Component Libraries and set it to be public as well. This will expose the component library to anyone who has access to the public app URL.
10. Switch component versions
To pin your app to the component version you just published, navigate to the Custom Component settings in your Retool app and change dev
to the latest version. This may require you to refresh the page to see the newly published version.
Examples
Refer to the custom-component-examples
GitHub repository for custom component examples.
Limitations
There are some limitations on how custom component libraries can be used.
- Custom component libraries aren't supported in Retool Mobile.
- Custom component library descriptions cannot be edited.
- Individual library revisions cannot be larger than 10MB, or 30MB in dev mode.
- Custom component libraries only load JavaScript and CSS files at runtime. Any other file included in the revision bundle is ignored.
- Node.js v20 or later is required for your development environment.
- Admin permissions in Retool are required.
- Custom components must be written in React and Typescript.
- When you download a page in PDF format, custom components are not included.
For Retool Cloud organizations, there is a 5GB limit on the total size of all custom component libraries within an organization. If you need to deploy new revisions and have reached this limit, you can free up space by visiting the Custom Components settings page and deleting some existing libraries.