# How to Create Responsive Layouts in Retool

- Tool: Retool
- Difficulty: Intermediate
- Time required: 20-30 min
- Compatibility: Retool Cloud and Self-hosted
- Last updated: March 2026

## TL;DR

Retool uses a 12-column grid for layout. Toggle between Desktop and Mobile views in the editor toolbar to configure separate layouts for each breakpoint. Use the Inspector's Layout section to set column spans, and enable/disable 'Show on mobile' per component. Stack components provide automatic responsive reflow. Add CSS media queries in App Settings → Custom CSS for fine-grained control.

## Responsive Design in Retool's Grid System

Retool's layout engine is built on a 12-column grid. Every component you place on the canvas occupies one or more columns, and you can configure these spans differently for desktop and mobile views. The editor provides a Desktop / Mobile toggle in the toolbar that lets you switch between two independent layout configurations for the same app.

Beyond the grid, Retool's Container and Stack components let you group related components. Stack components are especially powerful for responsive design: they reflow child components from horizontal to vertical automatically at smaller screen widths.

For cases where Retool's visual layout tools fall short — such as hiding entire sections conditionally, or applying pixel-precise spacing — you can supplement with custom CSS media queries in the App Settings. This tutorial covers all these techniques from end to end.

## Before you start

- A Retool app with multiple components across at least one page
- Editor or Admin access to the Retool app
- Familiarity with Retool's component Inspector panel
- Basic understanding of CSS media queries (helpful but not required)

## Step-by-step guide

### 1. Understand the 12-column grid layout

Every Retool canvas uses a 12-column grid. When you place a component, it snaps to columns. To configure a component's column span, select it and look at the Inspector panel's Layout section. You'll see Width (in columns, 1–12) and position controls. A full-width component uses 12 columns; a half-width uses 6. Components placed side-by-side occupy columns in the same row. Drag the right edge of any component in the editor to resize it across columns.

**Expected result:** You can see column grid lines in the editor and resize components by dragging edges.

### 2. Switch to Mobile layout view

In the Retool editor toolbar (top-center), look for the Desktop / Mobile layout toggle — it appears as a monitor icon and a phone icon. Click the phone icon to switch to Mobile layout view. In mobile view, the canvas shrinks to a phone-width representation. You can now independently rearrange, resize, and configure component visibility for the mobile breakpoint without affecting the desktop layout.

Changes made in Mobile view only affect mobile. Changes in Desktop view only affect desktop. The two layouts are fully independent.

**Expected result:** The editor canvas switches to a phone-width view and shows [Mobile] in the toolbar.

### 3. Configure component visibility per device

Select any component in the editor. In the Inspector panel, go to the Layout section. You will see a 'Show on mobile' toggle (and corresponding 'Show on desktop' toggle). Disable 'Show on mobile' for components that should be desktop-only, such as sidebars, data-dense tables, or wide charts. On mobile, these components will be completely hidden — they won't take up space in the layout.

For mobile-first content (e.g., a simplified summary card instead of a full table), build it in the Mobile layout view and disable 'Show on desktop'.

**Expected result:** Components with 'Show on mobile' disabled disappear from the mobile canvas view while remaining visible in desktop view.

### 4. Use Stack components for automatic reflow

A Stack component (found in the component panel under Layout) arranges its children horizontally or vertically. On desktop, set Direction to Horizontal for side-by-side cards. In the Mobile layout, select the same Stack and change Direction to Vertical — children will stack top-to-bottom. Stack also supports Wrap, which automatically wraps children to the next line when the container is too narrow.

Stack components work well for: navigation button groups, card grids, form field rows, and metric panels.

```
// Stack direction is set via Inspector — no code needed.
// But you can also control it dynamically:
// In Inspector → Direction, enter: {{ isMobile1.value ? 'vertical' : 'horizontal' }}
// where isMobile1 is a temporary state variable set by a window resize JS query
```

**Expected result:** On desktop, Stack children appear side-by-side. In Mobile layout view, they stack vertically.

### 5. Adjust font sizes and spacing in Mobile layout

Select a Text component in Mobile layout view. In the Inspector, you can set a smaller font size or different padding specifically for the mobile layout. For Table components on mobile, consider reducing the number of visible columns: select the Table → Inspector → Columns section → hide non-essential columns by unchecking their visibility.

For forms, reduce the number of columns in a Form component's grid from 2 to 1 on mobile by selecting the Form component in Mobile layout and adjusting its column count in the Inspector's Layout section.

**Expected result:** Text is smaller, form fields stack single-column, and tables show fewer columns on the mobile canvas.

### 6. Add CSS media queries for supplemental control

Open App Settings → Appearance → Custom CSS. Add media queries for fine-grained responsive control that Retool's visual tools don't cover. Common use cases: reducing padding, changing font weights, or hiding helper text on narrow screens.

```
/* Responsive font scaling */
@media (max-width: 768px) {
  ._retool-text {
    font-size: 13px !important;
    line-height: 1.5 !important;
  }
  
  /* Reduce table padding on mobile */
  ._retool-table td,
  ._retool-table th {
    padding: 6px 8px !important;
  }
  
  /* Stack component spacing adjustment */
  ._retool-container {
    padding: 8px !important;
  }
}
```

**Expected result:** Text and table cells shrink slightly on screens narrower than 768px.

### 7. Test the responsive layout in preview mode

Click the Preview button (play icon, top-right) to open the app in preview mode. Use browser DevTools (F12 → Device Toolbar, or Cmd+Shift+M) to simulate phone and tablet widths. Check that: columns collapse correctly, mobile-only components appear, desktop-only components are hidden, Stack components reflow vertically, and form fields are usable with a touch-simulated viewport.

For Retool Mobile (the native app), test using the Retool Mobile app on a real device connected to your Retool organization.

**Expected result:** At phone widths (375–430px), the app displays the mobile layout with hidden desktop-only components and vertical stacking.

## Complete code example

File: `App Settings → Custom CSS (responsive supplements)`

```css
/* ================================================
   Responsive Layout CSS Supplements
   These work alongside Retool's visual layout, not instead of it
   ================================================ */

/* Tablet: reduce padding density */
@media (max-width: 1024px) {
  ._retool-container {
    padding: 12px !important;
  }
  
  ._retool-button-primaryButton {
    padding: 8px 16px !important;
    font-size: 14px !important;
  }
}

/* Mobile: compact everything */
@media (max-width: 768px) {
  ._retool-text {
    font-size: 13px !important;
    line-height: 1.5 !important;
  }
  
  ._retool-table td,
  ._retool-table th {
    padding: 6px 8px !important;
    font-size: 12px !important;
  }
  
  /* Hide helper text labels on very small screens */
  .hide-on-mobile {
    display: none !important;
  }
  
  /* Make inputs full-width on mobile */
  ._retool-textInput {
    width: 100% !important;
  }
}

/* Extra small: phones in portrait */
@media (max-width: 480px) {
  ._retool-app-body {
    padding: 8px !important;
  }
}
```

## Common mistakes

- **Making layout changes in Desktop view and expecting them to reflect in Mobile view** — undefined Fix: Desktop and Mobile layouts are independent. If you add a component in Desktop view, switch to Mobile view and configure its position/visibility there separately.
- **Using absolute pixel widths on components that need to be responsive** — undefined Fix: Use column spans (1–12) in the Inspector's Layout section instead of fixed pixel widths. Column spans are proportional and adapt to the container width.
- **Relying on CSS alone for responsive behavior without using the Mobile layout toggle** — undefined Fix: Retool's Mobile layout gives you a proper separate layout canvas. Use it first, then supplement with CSS. Trying to do everything in CSS while ignoring the Mobile layout toggle is much harder.
- **Placing components inside a Stack and forgetting to set Direction to Vertical in the Mobile layout view** — undefined Fix: Select the Stack component while in Mobile layout view and change Direction to Vertical in the Inspector. This change only applies to mobile.

## Best practices

- Always configure the Mobile layout view explicitly — don't rely on the desktop layout scaling down gracefully
- Use Stack components for component groups that need to reflow; avoid manually positioning components that need to reorder on mobile
- Hide complexity on mobile: tables with 10+ columns should be replaced with a mobile-optimized card list in the Mobile layout
- Test responsive layouts using browser DevTools device simulation, not just by resizing the browser window
- Use the CSS Class Name Inspector field with .hide-on-mobile as a convention for elements hidden via CSS media queries
- Keep the mobile canvas to a maximum width of 390px to match modern iPhone viewport widths
- For Retool Mobile (native app) users, test on a real device — the web responsive layout and the native mobile app layout can differ

## Frequently asked questions

### Does Retool have a tablet/iPad breakpoint in addition to desktop and mobile?

Retool's visual layout editor only has two breakpoints: Desktop and Mobile. For tablet-specific behavior, you need to use CSS media queries in the Custom CSS area (e.g., @media (max-width: 1024px)). The Mobile layout in Retool targets phone-width viewports; tablets generally render the Desktop layout.

### Can I set different column spans for desktop vs mobile without switching layout views?

No. Column span configuration is separate per layout view. Switch to Mobile layout using the phone icon in the editor toolbar, select the component, and adjust its column span in the Inspector. This mobile span is stored separately from the desktop span and only activates when the app renders at a narrow viewport width.

### How do I make a Retool table usable on mobile?

In the Mobile layout view, select the Table component and in the Inspector's Columns section, uncheck the visibility of non-essential columns. Alternatively, hide the Table entirely on mobile (Show on mobile: off) and show a List component instead that renders the same query data in a mobile-friendly card format.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-create-responsive-layouts-in-retool
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-create-responsive-layouts-in-retool