App editor

The App editor is the interface you use to build Retool apps. It is made up of five primary areas:

• Canvas - Arrange components to build your app's interface
• Toolbar - Configure app settings
• Left panel - Visualize and browse component, query, and app state
• Bottom panel - Write code to query and transform data
• Right panel - Configure and create components

Canvas

The canvas is the main area of your Retool app and is where you build the interface. You arrange components by dragging them from the Create tab of the right panel. Components snap to the 12-column grid and can be placed in two specific sections, known as frames.

12-column grid

Both frames on the canvas use a 12-column grid that fills your viewport with fixed-height rows. The grid has a maximum width of 1560px and you can view it at any time by holding down Cmd/Ctrl.

As you arrange components in either frame, their position and size snaps to this grid.

Frames

📘

The Sidebar frame is available on Retool Cloud and on Self-hosted Retool versions 2.106 and later.

The canvas is split into three sections which contain components and serve different needs:

• The Header frame is primarily for custom app headers (app title, horizontal menus, etc.)
• The Main frame is the area that users interact with the most.
• The Sidebar frame is primarily for vertical navigation.

The Main frame is always present. You can configure Header and Sidebar frames using the Explorer.

Each frame automatically grows as you add or resize components by adding more rows to the grid.

Header frame

The Header frame allows you to build a custom header for your application. It initially contains a Navigation component which you can use as a horizontal navigation menu. You can also drag any component into this frame to customize it further.

The Header frame is always visible in creator mode. It is not visible in user mode if it doesn't contain any components. Your users only sees your custom header in user mode, not a Retool-branded header. To return to your app homepage, click on the Powered by Retool button.

Main frame

The Main frame is the core section of your application. This frame is where you place and arrange the majority of your app's components and in which most interactions take place.

Sidebar frame

📘

The Sidebar frame is available on Retool Cloud and on Self-hosted Retool versions 2.106 and later.

The Sidebar frame is primarily for building navigation into your apps. On first use, it initially contains the following components which you can use as a navigational sidebar:

• An Image component in the Sidebar header with a default logo.
• A Navigation component to the Sidebar body.
• An Avatar component in the Sidebar footer.

You can drag any components into the Sidebar frame in much the same way as the Header and Main frames. As the Sidebar frame is designed to appear vertically, it has specific size and layout constraints:

• Fixed 240px width.
• Positioned to the left of the Main frame.
• Rendered below the Header frame (if visible).

To hide the Sidebar frame, you can set the Hidden property to True in the Inspect tab, or use JavaScript and the .setHidden() method (e.g., sidebarFrame1.setHidden()).

The Sidebar frame is also optimized for mobile. It is hidden by default when viewed on a mobile device and is accessible using a menu button that is automatically included. When pressed, the Sidebar frame slides into view.

Arrange components

📘

Components are fully interactive in creator mode. Hold Cmd/Ctrl when selecting or moving a component without interacting with it.

Drag-and-drop components to rearrange them on the canvas. Components cannot overlap so, as you move components around, the layout of your app automatically updates and adjusts. All components have a default size (e.g., 2 columns x 5 rows) and built-in spacing.

Resize components

Most components can be resized to fit a custom area—select a component and then drag from a corner or edge. Certain components, such as Container or Text Area, have a fixed sizes that expand to automatically grow with their content. You can set their Overflow setting to Scroll or Hidden using the Inspect tab of the right panel to control this behavior.

👍

You can fine-tune the position of selected components using keyboard arrow keys.

You can configure containers to dynamically adjust their size based on their contents. Set the component's Height to Hug Contents in the component's Layout settings, available in the Inspect tab of the right panel.

Group components together

Retool provides flexible components to group other components together, such as Container and Form. These components extend the 12-column grid layout so you can drag components directly into a container in the same way as directly on the canvas. This creates a group of nested components. All components can be nested in this way.

Disable or hide components

Set a component's Disabled or Hidden setting to true to disable or hide it. These values can also evaluate to true based on a truthy value. For example, you can use the state of one component to toggle the Hidden property of another component. Checkbox can be used to toggle the visibility of another component when checked. To do this, set Hidden to {{ checkbox1.value }} on the component you want to hide . This evaluates to true when the checkbox is checked, and false when unchecked.

You can also use event handlers if you need to control components based on user actions. For example, you could use a Button to show or hide a Text Area component.

📘

Hidden components don't take up space on the canvas by default. You can enable Maintain space when hidden to preserve the component's layout regardless of visibility. This can maintain fixed positioning of components, regardless of visibility.

Duplicate components

You can duplicate existing components by holding Alt and dragging them to a new position. You can also copy and paste selected components using Cmd/Ctrl+C and Cmd/Ctrl+V.

Toolbar

The toolbar is the row of options to configure your app, displayed at the top of the App editor.

Some available options include:

• Set the name and description of your app, or write app documentation.
• Toggle the visibility of panels.
• Change zoom size.
• Toggle desktop and mobile layout views.
• Select the current environment.
• Access the App actions menu.
• Share the app with others.

You can toggle the visibility of the panels from the toolbar to provide more space to work in the canvas.

App actions

The ••• menu contains various actions and settings for your app.

Some available options include:

• Import or export an app as JSON.
• Duplicate an app or clone it as a module.
• Manage releases and history.
• Configure app settings such as themes and custom branding.
• Manage scripts and styles.
• Configure URL query parameters.
• Set custom keyboard shortcuts.

Share and preview your app

🚧

Some updates to the app sharing and preview features are currently being rolled out. You might not see these updates in the App editor yet.

Click Share in the top right to access available sharing options. You can share apps with other editors in your organization or invite new members to join. You can also share a viewer link that launches your app in user mode, or use the provided IFRAME snippet to embed your Retool app in another page.

Next to the Share button, there's a Preview toggle. You can click this button to quickly switch between Preview and Editor mode. If you use release management, you can also preview specific versions of apps.

You can also press Ctrl Alt Enter to toggle between Preview and Editor mode.

Left panel

The left panel contains the Explorer and State tabs, and provides you with a visualization of the contents of your app.

Explorer tab

The Explorer tab allows you to view and interact with the components and code used in your app. The Components tree gives you a nested view of all components in your app. You can select components and rename, switch, or delete them from the tree.

You can also view and select components that are not currently visible, such as those in Tabbed Container component views. Selecting a component makes it visible and, where necessary, switches a container's view to make it active.

The Code section contains all of your app's queries, transformers, and temporary state. Selecting an item automatically displays the bottom panel for you to make changes.

State tab

The State tab displays the current state of all code, components, and global parameters for your app. It organizes information into Components and Code sections that you can use to explore values across your Retool app, such as query data or component settings.

The structure maps to how you specify values in your app. For example, {{ query1.data.createdAt }} would return an array of createdAt data from query1.

Right panel

The right panel contains the Inspect and Create tabs. This is the panel you most interact with when building apps.

Inspect

The Inspect tab is commonly referred to as the Inspector. It contains all the available settings for the selected component and is where you set values, update component names, and create event handlers. The Inspector organizes settings into different sections, such as Basic and Interaction. These settings and sections change automatically as you select different components.

Create

The Create tab contains a library of all available components and modules. You use this tab to add components to your app; drag-and-drop a component from this tab to the canvas. It organizes components into sections and you can enter a search term to quickly find a component you need.

🚧

The Deprecated section contains older components that have been deprecated. You can automatically upgrade any deprecated components currently in use.

You can also use the Create tab to add modules—reusable groups of components and queries that you can embed into other apps.

Bottom panel

The bottom panel is where you write code to interact with connected resources. You can perform API requests, query databases, transform or manipulate data with JavaScript, and configure temporary state.

📘

The bottom panel displays queries or temporary state in your app if the Explorer tab in the left panel is not currently visible.

The bottom panel also contains a database browser to explore tables and columns in a connected resource.

General

The General tab contains the query editor. Queries can typically run automatically when inputs change or run only when manually triggered. You can write SQL queries using either SQL mode for reading data or GUI mode to write data using an interactive query builder. You can also configure query event handlers that trigger when a query runs or fails to run successfully.

📘

To protect your data, queries that perform write or delete operations (e.g., PUT requests or delete record queries) are initially set to be manually triggered.

Response

The Response tab allows you to configure actions and conditions once a query is run. You can configure notifications or customize failure conditions.

Advanced

The Advanced tab expands on the previous tab's settings. You can configure confirmation requests, timeouts, and disable queries under certain conditions. If you configure a query to run automatically on input change, you can specify which inputs to watch. This triggers the query only when a relevant input changes.

Desktop and mobile layouts

Retool apps support desktop and mobile layouts. You can optionally show or hide components on either layout by toggling the Responsive settings for each component. The mobile layout also uses a narrower 12-column grid to accommodate the smaller size.

Use the Desktop and Mobile buttons in the top bar to toggle between layout views. Components you add appear only in the layout you're currently viewing. For example, if you add a component while viewing the mobile layout, it does not appear in the desktop layout until you enable it. You can also customize the arrangement of components for each layout separately—repositioning a component in the desktop layout does not alter its position for the mobile layout.

All components appear on the desktop layout by default. The mobile layout is enabled when you configure at least one component to show on mobile. Apps automatically switch to the mobile layout when the viewport width is less than 600px wide.

Supported browsers

Retool officially supports the latest stable releases of the following desktop web browsers:

• Google Chrome
• Microsoft Edge
• Mozilla Firefox
• Apple Safari

Editing apps in alternative browsers, mobile devices, or beta and nightly builds, is not officially supported.