The Retool canvas now consists of two sections in edit mode: the Header and Main frames.

The Header frame is a new section of the canvas that allows you to build a custom header for your application. You can drag any component into it, like the new Navigation component, which allows your end users to navigate to other Retool apps or external links. The header will only appear in viewer mode if it has at least one component in it.

The Main frame is the core section of your application. Both frames are made up of a 12 column grid that stretches to fill your viewport and fixed-height rows. As you drag more components into either frame, its grid will grow with additional rows as needed. You can also move components between frames by dragging them.

Both frames have a max width of 1560px, but we’ll soon have a setting for you to configure it.


See the grid when dragging a component, or by holding down CMD/CTRL.

The Header and Main frames give you full control over the entire canvas of your application, so you can customize Retool applications to your liking. In viewer mode, your users will not see a Retool-branded header–just your custom header. To return to your app homepage, users can always click on the “Powered by Retool” button in the bottom-right corner. Only users in edit mode will see the Retool header so they can easily return to editing their app.

Custom header in viewer modeCustom header in viewer mode

Custom header in editor preview modeCustom header in editor preview mode

Arranging components

Components are the basic building blocks of any Retool app. There are 40+ components to choose from in the Components tab of the right-hand panel, from a simple Text Input or Button to a Table, Chart, or Form. Add a new component to your app by dragging it onto the canvas:

Some components have default data when you drag them onto the canvas. Read more about configuring your components (e.g. connecting to the results of a query) in Working With Components.

All components have a default size (e.g. 2 columns x 5 rows) and built-in spacing. Drag and drop to rearrange components on the canvas, and you’ll get a live preview of how your layout will reflow. Use your arrow keys to move components within available space:


In edit mode, components on the canvas are still fully interactive, which can sometimes interfere with drag-and-drop. CMD/CTRL and click to select or drag a component without interacting with it.

Click and drag to select multiple components, or CMD/CTRL and click to add components to your current selection:

First select a component, and then resize by its corners or any of its edges:


If you ever want to cancel an in-progress drag or resize, hit ESC

Duplicate a component by holding ALT and dragging to the desired position for the new component:

Grouping components together

Retool provides flexible container components that have their own internal, 12-column grid. You can drag components directly into a container, and containers can also be nested within one another:

Most containers can be dynamically sized based on their contents. Set “Height” to “Hug contents” in the right-hand panel under “Layout.”

For containers with a fixed height, you can set overflow to “Scroll” or “Hidden.” Some containers also offer “Visible” overflow. When “Scroll” is selected, you’ll always see the scroll bar in editor mode, but your app viewers will only see it when there is content to scroll:

Tabbed Container

Tabbed Containers allow you to create any number of tabs, each with their own grid of components. Hover over the tab name to drag components back and forth:

When “Hug contents” is enabled, the Tabbed Container will resize to the content of the currently selected tab.


Another container component is the Modal, which pops up a new container on button click. To add components to a Modal, drag the component onto the “Open Modal” button. Similarly, hover over the modal X button while dragging to close it:


Forms let you group inputs together, so you can submit them at once. Drag any component into a Form. Components with a value (e.g., TextInput, Checkbox) will be included in the submitted form data:


ListView allows you to create repeatable rows of components. Read more in Working With ListViews to learn how to connect them to the results of a query. Rearrange components in the first row to affect all of the rows:

Dynamic layouts

Hidden components

Components in Retool can be hidden based on any boolean condition. Let’s say you want to hide a component whenever we check a Checkbox. Select the desired component, go to the “Display” section of the right-hand side Inspector, and add {{ checkbox1.value }} to the “Hide when true” field. When a component’s “Hide when true” is truthy, that component stops taking up space in the Retool grid. Other components will shift up to fill that whitespace:


If your condition cannot be evaluated (e.g. waiting for a query result to return), your component will default to hidden.

Responsive design

In order to show a Retool component on mobile, toggle “Show on mobile” in the right-hand panel Inspector. Then, view your app’s Desktop and Mobile layout by toggling the Desktop/Mobile icons in the top bar:

Did this page help you?