Skip to main content

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:

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.

git clone https://github.com/tryretool/custom-component-collection-template 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.