Retool Mobile app design and layout

Learn how to design Retool Mobile apps and customize their layout.



Retool Mobile is currently in private beta. Sign up to join the waitlist β†’

You can customize the appearance and layout of mobile apps in a number of ways. Use Collections to display data using prebuilt card and list layouts, or create your own with mobile components. Configure your app's layout and tailor the design to meet your needs, and include additional UI elements to further extend functionality.


Collections are mobile components that dynamically map items from a data source and present them using a repeating row layout. You configure row data using the Mapped options settings in the Inspector.

Card Collection and List Collection mobile components presents image and text values using a prebuilt layout. You can also create your layout of mobile components with Custom Collection.

Card Collection

Card Collection renders each row of data using a card layout that puts focus on an image, with text information displayed below.

Card Collection with horizontal scroll, half-size, and full-sizeCard Collection with horizontal scroll, half-size, and full-size

You can control the appearance of cards using the Data Layout settings in the Inspector. Options include:

  • Style: Flat renders cards without a background and applies rounded corners to images. Elevated renders cards with a distinct border, shadow, and padding.
  • Scroll: Vertical renders cards in a vertically scrolling column. Horizontal renders cards in a horizontally scrolling row.
  • Size: Full renders full-size cards. Half renders half-size cards. If Scroll is set to Vertical, cards are displayed as either a single column or two-column grid.

You can also configure the image dimension ratio, such as 1:1 or 4:3 to display images to best fit your needs.

List Collection

List Collection renders each row of data using a list layout that combines an image or icon with text information.

List CollectionList Collection

You can control the appearance of list items using the Data Layout settings in the Inspector. Options include:

  • Style: Flat renders list items with no margin or background, and can include an optional separator between list items. Elevated renders list items with a distinct border, shadow, and padding.

Custom Collection

Custom Collection allows you to build your own collection using other mobile components. This gives you control over which mobile components to include.

Custom CollectionCustom Collection

You add mobile components to a Custom Collection by clicking the + button or dragging them into the collection. You also use item and i to reference the current data source and set these as values for each mobile component.

Select collection items

You can configure event handlers to trigger an action when a user selects a collection item, such as navigating to another screen or triggering a query. When a user selects an item, the item's data is stored in the collection's selectedItem property. This allows you to use details about a selected item elsewhere.

For example, each item contains a URL, item.url, to a web page that should open when selected. To achieve this:

  1. Select a collection and click + Add in the Interaction settings to add an event handler.
  2. Set the Action to Open URL
  3. Set the URL to {{ self.selectedItem.url }}

When an item is selected in a collection, the mobile app opens the web page using the URL of the selected item.

Customize app layout

Retool Mobile apps arrange mobile components in column (vertical) and row (horizontal) layouts. By default, all mobile components are full-width and stack vertically, with new mobile components added to the bottom of the app.

Horizontal layout of components

You can nest mobile components within a Container mobile component to arrange them horizontally. This enables additional layout settings for certain mobile components to control width and alignment.

Horizontal row layoutHorizontal row layout

  1. Click + in the Components section and add a Container mobile component to your mobile app.
  2. Add some mobile components to this Container, or drag existing ones into it.
  3. Configure the Container to arrange nested mobile components in a row layout by selecting a Layout type of ➜.

Once enabled, mobile components within this Container appear horizontally.

Configure mobile component width

You can configure certain mobile components to use a fixed width. Use the Layout settings in the Inspector and configure its Width to X (fixed). When enabled, the mobile component's width automatically adjusts based on its content, such as the text it contains.

Configure widths for mobile componentsConfigure widths for mobile components

If you don't enable fixed width for all nested mobile components, any other mobile components that are set to full width will take up the remaining space.

Align fixed-width mobile components

If you enable fixed-width for all nested mobile components, you can configure a Container with Justify (horizontal alignment) and Align (vertical alignment) settings to further refine the layout.

Use the Justify settings in the Basic section of the Inspector to control the horizontal alignment of nested mobile components. You can align left, center, right, or distribute evenly to fill the entire space.

Justify alignment of componentsJustify alignment of components

Certain mobile components, such as Button, have a Size setting with options for Small or Large. If there is a mix of sizes across nested components, you can use the Align settings to vertically align top, middle, or bottom.

Gap and padding

If you use nested mobile components extensively, you can use Gap and Padding settings to fine-tune their layout.

  • Gap controls the space between nested mobile components.
  • Padding controls the space surrounding all nested mobile components.

Adjust gap and paddingAdjust gap and padding

You may need to adjust these settings whenever you make significant changes to your app's layout.

Separate layout areas

Use the Divider and Spacer mobile components to visually separate vertical areas of your mobile app with dividing lines or empty blocks of space.

Spacer and Divider mobile componentsSpacer and Divider mobile components

Sheets, modals, and notifications

Retool Mobile event handlers include actions to display supplemental UI elements with additional actions or information.

Action sheets and alerts are modals that provide additional information and event handler actions for users to select. These actions allow users to trigger queries, navigate to a screen, etc. Both Action sheets and alerts can also include a title and description, allowing you to provide more context to users.

Display an action sheet

An action sheet is an overlay modal that appears at the bottom of the screen. It contains a title and description, along with a list of actions from which a user selects, along with a Cancel button.

The action sheetThe action sheet

To create an action sheet:

  1. Add a new event handler.
  2. Set the Action to Action sheet.
  3. Click + New to add a new action to the sheet.

Display an alert modal

An alert is a modal that appears at the center of the screen. It contains a title and description, along with a maximum of two actions.

Alert modalAlert modal

To create an alert:

  1. Add a new event handler.
  2. Set the Action to Alert.
  3. Click + New to add a new action to the alert.


A notification is an informational modal that appears at the bottom of the screen.

Notification in Retool MobileNotification in Retool Mobile

To create a notification:

  1. Add a new event handler.
  2. Set the Action to Notification.
  3. Specify the Title, Description.
  4. Select the Type of notification

The notification's Type reflects the severity of the notification, changing the icon and color used. You can also control the duration that notifications remain on the screen.



Retool Mobile app themes function separately from Retool web app themes.

You can create and manage custom styling for your mobile apps with themes. To customize your app's theme, click the β€’β€’β€’ App actions menu and select App theme.

  • Primary: The default accent color used by most mobile components.
  • Header: The background color for the title area of screens.
  • Buttons: The corner style for buttons.

Mobile app themeMobile app theme

You can create custom themes and apply them to your mobile apps.

Did this page help you?