How to build your first Retool dashboard

Dashboards are one of the most popular things to build in Retool. Most teams already have the data they need sitting in a data warehouse, but getting that in front of people in a format where they can understand and gain insights from is the hard part.

Your data team might be able to help, but if they’re busy with other projects, you could be waiting a while. Or you could use Retool to describe the dashboard you want in plain language and get a React app connected to your data.

In this tutorial, we’ll cover how to connect data, generate a revenue dashboard with interactive charts, tables, filters, and drill-downs, and refine and publish it as a tool your team can use.

What we're building

What goes into a dashboard depends entirely on the data underneath it. A revenue dashboard and a support-ticket dashboard share almost nothing in their specifics. But a few elements are close to universal: headline numbers at a glance, a trend over time, a breakdown by category, and a way to reach the underlying records.

Here, we're building a revenue dashboard that includes:

KPI cards: Total revenue, order count, average order value
Trend chart: Weekly revenue visualization
Category breakdown: Revenue by product category
Order table: Recent orders with interactive filters
Drill-downs: Click to view order details in a slide-out drawer

As the data dictates the dashboard, here is also the sample dataset we’re using:

orders.csv - 150 orders
categories.csv - 6 product categories

The orders table has the columns you'd expect from an order system, including region, total, and status, and each order belongs to one of six product categories. That's enough structure to make the filters and drill-downs meaningful. Everything here works the same way against your own data—we’re just using a sample file for this tutorial so we're all looking at the same thing.

Step 1: Connect your data source

Connecting data first is a convenience rather than a requirement. If you prompt without naming a data source, the agent inspects the schemas of your available resources and suggests one. Connecting in advance and naming the resource in your prompt skips that investigation, so the agent starts with the right schema immediately.

Option A: Retool Database (fastest)

Retool Database is a managed PostgreSQL database with a spreadsheet-style interface, which makes it a good default while you're learning.

1.
Go to Resources > Create new > Resource.
2.
Select Retool Database.
3.
Click the + button on the left, then select Import from CSV and upload orders.csv and categories.csv.
4.
Tables are created automatically with the correct schema, including typed columns.

Once the import finishes, you'll see both tables in the spreadsheet view. It's worth clicking into the orders table and skimming it for a moment, because knowing what the columns actually look like makes it much easier to write a good prompt in the next step.

Option B: Connect an existing database

For production data, connect to your existing data sources instead:

1.
Go to Resources > Create new > Resource.
2.
Select your database (Postgres, Snowflake, MySQL, BigQuery, Databricks) or API.
3.
Configure the connection details.
4.
Name it clearly, like analytics_warehouse, since you'll reference it by name when prompting.

Step 2: Generate your dashboard with a prompt

With data connected, it's time to create the app. The agent builds the entire first version from your opening prompt and the schema it reads from your resource, so the detail you put in here sets how close that first version lands to what you want. A vague prompt still produces a dashboard, just one you'll spend more rounds correcting.

Create your app from a prompt

1.
From the Retool home screen, click Create > App.
2.
In the Chat tab, write your prompt. @-tag your resource by name, like @retool_db, so the agent connects to the right data source and reads the schema.

Here's an example of what an effective prompt looks like:

Build a revenue dashboard using my @retool_db orders table.

Include:
- KPI cards showing total revenue, order count, and average order value
- A line chart showing weekly revenue trends
- A bar chart breaking down revenue by category (join to @retool_db categories table)
- A table of recent orders with columns: id, created_at, customer_id, region, total, status
- Filters: date range (default last 90 days), region multiselect, category multiselect

Place KPIs at the top, charts in the middle, and the table at the bottom.

This prompt works for a few reasons:

It @-tags the data source, so the agent reads the real schema instead of guessing at table and column names.
It specifies the exact components, so the agent doesn't have to infer how you want the data presented.
It describes the layout in plain terms, top to bottom.
It asks for things a teammate could maintain, by naming specific columns rather than leaving the agent to pick.

Notice it also sets a default for the date filter. Small decisions like that are exactly what you'd otherwise spend follow-up prompts correcting, so front-load the ones you already know. The prompting best practices doc goes deeper on what the agent responds well to.

Now send it. The agent builds the dashboard on the preview canvas in real time. The canvas remains interactive during the build, so you can click a filter or open a row while components are still being rendered. If the KPI cards populate with numbers that look wrong, or the chart buckets by day when you wanted weeks, you'll catch it now rather than after the fact.

What the agent generates

When the build finishes, the agent will have produced:

A React component tree for the KPI cards, charts, table, and filters, rather than a grid of dragged widgets.
Strongly typed, serverless TypeScript functions that read from your resource, rather than freestanding SQL queries.
Wired data connections between those functions and the components.
A mobile-responsive layout.

If you've used AI tools that show a diff for you to approve before anything lands, note that this works differently. The agent operates directly on the app's source code, while the review points sit elsewhere.

The Code tab shows everything it generated, at any time, and any function that writes data waits for your explicit approval before it runs. We'll come back to that second part in Step 4, because it matters once your dashboard does more than read.

Step 3: Refine with follow-up prompts and code

The first version will be close but probably not finished. Next, you’ll look at what the agent made, notice what's off or missing, and push it in the right direction. You can do that through follow-up prompts, Selection mode, or direct code edits, and you can mix all three freely.

Follow-up prompts in the Chat tab

Most refinement is just telling the agent what you noticed. A few examples of the kind of request that works well:

“Add a filter for category when the category selector has a value.”
“Move the filters above the charts and make the orders table full width.”
“Apply a red background to rows where status is ‘cancelled’.”

That last one is how conditional formatting works now. Describe the rule, like highlighting orders over $200 in green and canceled orders in red, and the agent writes the conditional logic into the component code.

Follow-up prompts also handle bigger additions. Our dashboard still needs its drill-down, so let's add that the same way:

Add a drill-down to the recent orders table. When a user clicks a row, open a slide-out drawer showing the full order details, including customer, region, category, status, and total.

Scoped edits with Selection mode

Sometimes you want to change one thing without risking the agent touching the rest. Click the Selection mode icon in the canvas toolbar, click a component, then prompt. The change applies only to that element.

Our trend chart has a real example of where this helps. The last data point drops off because the final week is partial, so select the chart and prompt:

Only include complete weeks so the line doesn't drop off at the final partial week.

The agent fixes the chart's function and touches nothing else. It's a small feature that becomes a habit once the app has enough pieces that "the chart" could mean several things.

Edit the code directly

Prompting covers most changes, but sometimes you know exactly what you want, and it's faster to write it yourself. The Code tab exposes the full React code and TypeScript functions the agent has generated, and you can edit any of it directly.

The Data tab in the left panel lists every function in the app along with the resources each one uses. From the Data tab, the Function playground lets you run an individual function with sample parameters and inspect its output before the UI depends on it. It's the quickest way to confirm, say, that the weekly revenue function buckets dates the way you expect.

The data concepts doc covers functions in more depth.

Step 4: Add interactivity

A dashboard gets more useful once people can act on what they see. Someone spots a dip in the trend chart and wants to know which category caused it, or sees an odd order in the table and wants the full record. Retool supports the usual patterns for this:

Chart interactions allow clicking a data point to filter other components.
Row actions add buttons to table rows for things like view, edit, or delete.
Drill-downs open drawers or modals to show detail without leaving the page.
Form submissions update data and refresh the display automatically.

Add chart interactivity

Let's make the bar chart drive the rest of the dashboard, so clicking a bar answers that “which category caused this?” question directly. Describe the interaction in the Chat tab:

Make my category bar chart interactive. When a user clicks a bar, filter the orders table, KPI cards, and trend chart to show only data for that category. When nothing is selected, show all data.

The agent adds the selection state and updates the relevant functions to filter on the chosen category. Then test it the way a teammate would use it. Click a bar to narrow the KPI cards, trend chart, and table to that category, then click away and confirm everything resets.

One thing to know before you add anything that writes data, like an editable status column or a form for correcting orders. Functions that add, delete, or modify data need your approval in the Chat tab before the agent runs them, and every function has to be approved before you can publish. That's deliberate. An agent that can build an app in minutes could also run a write you didn't intend, so a person stays in the loop for every one of them.

Step 5: Publish, secure, and share

Publish your dashboard

When the dashboard is ready, click Publish in the top-right corner of the builder. Because publishing replaces whatever version your team currently sees, Retool runs a checklist first, which confirms two things:

Every write function has been approved. If any haven't, you'll be prompted to review them.
Your changes don't conflict with the published version or with other users' changes.

Then name the app URL and pick a folder for it. The publishing guide has the details.

Control access with permission groups

Once it's published, sharing is just sending the URL. Deciding who can do what with the dashboard is the part worth a minute of thought, and that's what permission groups are for. Create groups that reflect how your team works. Common patterns include:

Analysts get view-only access, with Use permissions to run the dashboard and filter data.
Operators can interact with forms and edit specific fields, with Use and Edit permissions, but can't modify functions.
Admins get full control, with Own permissions to modify functions, manage permissions, and deploy changes.

From the Retool homepage, go to Settings > Permissions to create custom groups or use the defaults (All Users, Admin). For each group, set app permissions to Use, Edit, or Own. You can also configure resource permissions by environment, for example giving developers Edit access to staging resources while restricting production access.

Retool apps ship with strong security defaults, including SOC 2 Type II compliance, granular permissions, audit logs, and environment-level resource access. You can deploy on Retool Cloud or self-host on your own infrastructure, integrate your existing identity provider, and use role-based access control to meet your organization's requirements.

Where to go next

Once you've built your first dashboard, try building another one on top of your own data. The patterns you learned here apply to virtually any dashboard use case.

A good next step is a dashboard that acts on its data, with row actions or approval flows for updating records. The same prompt-and-refine loop covers those too, and the function approval flow you saw in Step 4 is what keeps those writes safe.

This article was originally published in December 2025. It was most recently updated in September 2026.