Techniques and examples to improve the design and usability of your Retool apps.

Improving the appearance of your Retool apps

A few simple techniques that you can use to improve the design & usability of the tools you're building for your team.

Use Color

Color is one of the most effective ways to communicate status or importance to your users. Many components in Retool have give you the ability to customize color: Buttons, Modals, Containers, Tables, Progress Indicators, Charts, etc.

Customizing a button color. We provide default choices that meet accessibility standards, but you can also set your own custom color with a hex code.

Adding a background color to a table color with a hex code. Since this input accepts Javascript, you can also set dynamic values like {{ self > 0 'green' : 'red' }}, which shows positive numbers in green and negative numbers in red.

When you add a background color to a table column, you can supply a hex code like #ffcc33, a CSS color keyword like greenyellow, or even add a Javascript expression to conditionally color cells based on its value, as seen in the above screenshot.

Containers currently have 3 options for colors: white, blue, and gray.

Format values to help users

Use custom formatting to present data to your users more accurately and more clearly. This is particularly helpful for date, currency, percent and other data types represented in tables and charts.

For example, if your database returns the price of a $50 item in cents (i.e. 5000), we can easily convert this to a more human readable format by selecting USD (cents) from the Column type dropdown.

Some component, like the table, have formatting presets; however, you can also use Javascript inside {{ }} to format values as needed. Retool includes a few handy utility libraries like MomentJS and numbro to make this even easier.

The table column type offers presets, like USD (Cents) to reformat data in the column to a friendlier format.

Using the included MomentJS library to reformat a date string to a format that's easier to read.

A few simple formatting tweaks make the blue chart on the right much more readable. In this example we are using the Y-Axis formatter to make the revenue numbers appear as dollars using the included Numbro javascript library.

Tips for common components

Text components can render as plaintext, HTML, or Markdown. This is helpful for a number of use cases like quick formatting and rendering HTML content. Try something like this:

Markdown in a text component

# This is an h1 heading
## This is an h2 heading
This is just normal text with some **bold** formatting*

HTML in a text component

<b>Name:</b> {{name.value}} 
<b>DOB:</b> {{dob.value}}

Table components have many formatting options and settings. A few that are particularly useful:

  • Compact mode for rows
  • Useful column types: dropdown, checkbox, input, boolean, button, URL link, etc
  • Render column data as HTML (you can even render images this way)
  • Column settings: mapper, background color, alignment

Group components into containers

Organization in your apps will help users know which components are supposed to work together. We have a few different containers to group components in Retool.

Our standard Container component is a great way to group similar elements. You can also add titles to these containers and pick a background color too.

You can also use Tabbed Containers to group similar elements that relate to a parent component. For example, if you are building a user admin console, you could have a tabs for: Overview, Billing Details, Usage Stats, and Feature Flags.

A tabbed container with some charts.

Forms are another type of container that you can use to group inputs for your users. Grouping inputs makes it easier for your users to complete common actions like creating new records or updating existing ones.

A simple form

List view containers are useful for showing repeating rows components of unknown length (like tables) but they also enable you to house any other component in their rows. Learn about the magic i variable and more in our list view guide.

Modal components are great for additional context, details, or settings that you want to hide from the main view, but still have accessible to your end users.

Hiding and disabling components & queries

One of the most effective ways to highlight the right path for your users is to show them only what you want them to look at. Luckily you can disable or hide any component in your app dynamically.

Each component has a setting to Hide when true which allows you to hide components dynamically when certain conditions are met. This can be useful for:

  • Hiding components until certain queries completed.
  • Hiding a container of advanced filter settings until a toggle has been switched on.
  • Hide a “detail view” container until a user selects a row from a table.

Most components and queries also have a Disable when true setting which allows you to dynamically disable them under certain conditions. This can be useful for:

  • Disabling a submit button on a form until a user uploads a file or fills in all form fields.
  • Disabling a button that triggers a query until a checkbox has been checked.
  • Disable queries from running until you select a particular tab in a tabbed container.


Tip: Always show hidden components in edit mode

In situations where you want to hide components from your end users, you often still want those components to show up in edit mode. That way you can still edit their properties, settings, placements, etc!

To ensure these components still show up while you're editing the app, enable the option to Always show in edit mode.

Enable the option to Always show in edit mode so that your hidden components show up while you're editing the app. You will see a red outline around these components, like button2 above.

Multi-page apps

Retool also lets you build multi-page applications by passing URL parameters from one app to another. If the time comes that you feel your monolith is becoming unwieldy (either to maintain or to use) it might be time to break it up into 2-3 smaller apps. See more info about URL parameters and multiple page apps in our guide.

Contextual information

It’s helpful to provide your users some context about what they are doing. Retool offers default and customizable notifications as well as some global variables that can help!


When a query runs successfully, you and your end users will see a toast message at the top of the screen. If you set your query to “Run when manually triggered” you will be able to customize a few other properties of your notification.

  • You can optionally customize or disable the default success toast message.
  • You can show a confirmation modal before running the query with customizable text.
  • You can also fire confetti when the query finishes! 🎉

Beyond the default notifications, we also include a utility function utils.showNotification() that you can use in Javascript Queries to create custom toast notifications. More info here.

Global Context

Retool also provides variables for the current_user and retoolContext which allows you to access more information about the user. For example, you could display a welcome message by using Welcome to your support portal {{current_user.firstName}}!.

Tooltips & placeholder text

Most components have a built-in tooltip feature that will show your end users more information on hover. This can help clarify ambiguous form inputs or specify they type or format of the value accepted by an input.

How tooltips appear for your end users.

Custom Themes

Add your own custom color themes to individual Retool apps or even globally across all Retool apps.

Customizing a theme for your Retool apps.

Mobile and desktop layout

By default, the Retool editor will start you in desktop view. However, you can also customize the mobile experience as well. You can switch between the two layouts by clicking the toggle in the navigation bar.

When you first click on the mobile icon, your app canvas might appear blank, that’s because components are hidden on mobile by default. To display component on mobile, select a component and then enable it on mobile by toggling on the Show on mobile this switch.

Toggle on the Show on mobile switch to add this component to the mobile layout.

Mobile layout is distinct from the desktop layout. You can change the layout, size, and visibility of components to make your user experience great on all devices.

Updated 4 months ago

What's Next

Learn more about applying themes to apps and customizing the layout for mobile view:

Customize mobile and desktop layouts


Techniques and examples to improve the design and usability of your Retool apps.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.