How to Create Custom Components in Retool

Open your terminal and create a new directory for your component library. Run `npx @tryretool/custom-component-support@latest init my-retool-components` to scaffold the project. The CLI will prompt you for your Retool instance URL and API token — enter your org URL (e.g., https://yourcompany.retool.com) and paste your API token. The scaffold creates a React + TypeScript project with Vite, the @tryretool/custom-component-support package pre-installed, and an example HelloWorld component.

1npx @tryretool/custom-component-support@latest init my-retool-components
2cd my-retool-components
3npm install

Open src/index.tsx to see how the scaffold uses Retool hooks. The key hooks from @tryretool/custom-component-support are: Retool.useStateString(key, defaultValue) for string state, Retool.useStateNumber() for numbers, Retool.useStateBoolean() for booleans, Retool.useStateObject() for objects, and Retool.useEventCallback(eventName) to fire Retool event handlers. Each useStateXxx hook returns a [value, setValue] tuple — setValue() writes back to Retool's component Inspector model, making it visible to other components via {{ customComponent1.model.yourKey }}.

1import Retool from "@tryretool/custom-component-support";
2
3export const MyComponent: FC = () => {
4  const [label, setLabel] = Retool.useStateString("label", "Hello");
5  const [count, setCount] = Retool.useStateNumber("count", 0);
6  const fireClick = Retool.useEventCallback("onClick");
7
8  return (
9    <button onClick={() => { setCount(count + 1); fireClick(); }}>
10      {label}: {count}
11    </button>
12  );
13};

Replace the scaffold content in src/index.tsx with a component that accepts a data array from Retool. Define a useStateObject hook named 'rows' — in the Retool app, you'll bind this to {{ query1.data }}. In your component, map over the rows array to render custom HTML. This pattern lets you build tables, cards, or any layout that Retool's built-in Table component cannot express, while still pulling live data from Retool queries.

1import Retool from "@tryretool/custom-component-support";
2import React, { FC } from "react";
3
4interface Row {
5  id: number;
6  name: string;
7  status: "active" | "inactive";
8}
9
10export const StatusCardList: FC = () => {
11  const [rows] = Retool.useStateObject("rows", []);
12  const onSelect = Retool.useEventCallback("onRowSelect");
13
14  return (
15    <div style={{ display: "flex", flexDirection: "column", gap: 8 }}>
16      {(rows as Row[]).map((row) => (
17        <div
18          key={row.id}
19          onClick={onSelect}
20          style={{
21            padding: 12,
22            borderRadius: 6,
23            background: row.status === "active" ? "#d1fae5" : "#fee2e2",
24            cursor: "pointer",
25          }}
26        >
27          <strong>{row.name}</strong> — {row.status}
28        </div>
29      ))}
30    </div>
31  );
32};

In src/index.tsx, ensure your component is the default export or is registered with defineComponent({ name: 'StatusCardList', component: StatusCardList }). Run `npm run dev` to start the local Vite dev server. The CLI automatically creates a temporary draft in your Retool org — open Retool in your browser and find the Custom Component Library in the component panel (it will show as 'Local Dev'). Drag it onto your canvas to test your component live with hot reloading.

1// src/index.tsx — register your component
2import { defineComponent } from "@tryretool/custom-component-support";
3import { StatusCardList } from "./StatusCardList";
4
5defineComponent({
6  name: "StatusCardList",
7  component: StatusCardList,
8});

With the StatusCardList component on the canvas, click to select it and open the Inspector panel. You should see a 'rows' property under the Model section. Set its value to {{ query1.data }} — replace query1 with your actual query name. Now when query1 runs, its data array flows directly into your React component's useStateObject('rows') hook. You can also bind static arrays or use transformer data: {{ transformer1.value }}.

In the Retool Inspector for your component, scroll to the Interaction section. You should see an 'onRowSelect' event listed (matching the name you passed to useEventCallback). Click '+ Add handler' and configure it to trigger a query or set a temporary state variable. For example, set a Temporary State variable selectedId to {{ customComponent1.model.id }} to capture which card was clicked. This bridges your custom component back into Retool's event/state system.

When development is complete, stop the dev server and run `npm run deploy` to publish your component library. The CLI will prompt for a version name (e.g., v1.0.0) and upload the built assets to your Retool org. Deployed versions are immutable — once published, a version's code never changes, giving your apps stable, reproducible builds. In Retool, switch from the 'Local Dev' version to the published version by opening the component's Library Version dropdown in the Inspector.

1npm run deploy