# How to Customize UI Components in Retool

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

## TL;DR

Retool components are customized at three levels: Inspector panel properties (colors, labels, sizes — no code needed), the Theme Editor for app-wide design system settings, and Custom CSS using ._retool-* selectors with !important for overrides the Inspector can't handle. Start with the Inspector and Theme Editor; only write CSS when you've exhausted those options.

## The Retool UI Customization Hierarchy

Retool provides four layers of UI customization, each with different scope and flexibility. Understanding which layer to use for which job saves significant time.

Layer 1 — Inspector Properties: The most direct way. Select any component and use the Inspector panel to change color, label text, disabled state, size, border radius, and dozens of other visual properties. No CSS or code needed.

Layer 2 — Theme Editor: App Settings → Appearance → Theme Editor sets organization-wide defaults for primary color, font family, border radius, spacing, and more. Changes here affect every component in the app that hasn't been individually overridden.

Layer 3 — CSS Class Names: Assign a custom class via Inspector → Advanced → CSS Class Name, then write scoped CSS rules in Custom CSS. Best for component-instance-level customization.

Layer 4 — Custom CSS: For everything else. Use ._retool-* selectors with !important in App Settings → Custom CSS (per-app) or Settings → Preloaded CSS (org-wide).

This tutorial walks through each layer with practical examples.

## Before you start

- A Retool app with several components to customize
- Editor or Admin access to the Retool app
- Basic CSS knowledge (helpful for layers 3 and 4)
- Access to your organization's brand colors/fonts if doing brand work

## Step-by-step guide

### 1. Use Inspector properties for direct component customization

Select any component in the editor. The Inspector panel on the right shows all configurable properties organized into sections: General (content, labels, placeholders), Interaction (event handlers, disabled, loading), Layout (width, height, padding), and Advanced (CSS Class Name, visibility). For visual customization, explore the Style section — most components have Color, Border color, Background color, Border radius, and Font size fields that accept hex values, CSS color names, or `{{ }}` expressions.

For Button components: Style section → Color (background), Label color, Icon color, Border radius. For Text components: Style section → Font size, Font weight, Color, Line height. For Table: Inspector → Columns → click a column → Column style for per-column customization.

**Expected result:** Component appearance changes immediately in the editor when you update Inspector style properties.

### 2. Set up the Theme Editor for app-wide defaults

Open App Settings (gear icon) → Appearance → Theme → Theme Editor. The Theme Editor shows global design tokens:

- Primary color: used by buttons, links, selected states
- Success/Warning/Error colors: used in alerts, badges, validation
- Background colors: canvas, component surfaces
- Border radius: applied to all components by default
- Typography: font family, base font size

Changes in the Theme Editor cascade to all components that haven't been individually overridden in the Inspector. This is the most efficient way to brand an app — set once, applies everywhere.

**Expected result:** All components update to use the new primary color and border radius. Components with Inspector overrides keep their individual styles.

### 3. Override individual component styles in the Inspector

After setting a global theme, override individual components as needed. Select a Button component → Inspector → Style → change Color to a specific hex value for that button only (e.g., #EF4444 for a destructive delete button). This per-component override takes precedence over the theme.

Key customizable properties by component type:

Button: Background color, Label, Icon, Icon position, Size (small/medium/large), Shape (default/circle/round), Loading state
Text: Font size, Font weight, Color, Horizontal/Vertical alignment, HTML mode
Container: Background color, Border, Border radius, Shadow, Padding
Table: Row height, Striped rows, Column widths, Cell alignment
Input: Placeholder, Prefix/Suffix text, Max length, Disabled state

**Expected result:** Individual components display their overridden styles while the rest of the app follows the theme.

### 4. Assign CSS Class Names for scoped styling

For customization not achievable through the Inspector alone, assign a CSS Class Name in the Inspector's Advanced section. This adds a wrapper class to the component's DOM element, enabling targeted CSS rules.

Select a component → Inspector → Advanced → CSS Class Name → type a name (e.g., danger-button, card-header, stat-primary).

Then write CSS in App Settings → Custom CSS targeting that class with ._retool-* descendant selectors:

```
/* In App Settings → Custom CSS */

/* danger-button class on a Button component */
.danger-button ._retool-button-primaryButton {
  background-color: #DC2626 !important;
  border-color: #DC2626 !important;
}

.danger-button ._retool-button-primaryButton:hover {
  background-color: #B91C1C !important;
}

/* card-header class on a Text component */
.card-header ._retool-text {
  font-size: 11px !important;
  font-weight: 700 !important;
  text-transform: uppercase !important;
  letter-spacing: 0.1em !important;
  color: #6B7280 !important;
}
```

**Expected result:** Only components with the specified CSS Class Names receive the scoped styles.

### 5. Customize component states (hover, disabled, loading)

Component states (hover, active, disabled, loading) can be styled via both Inspector and CSS. The Inspector provides a Loading property (boolean) and Disabled property for most interactive components — bind these to `{{ }}` expressions for dynamic states.

For CSS-based state styling:

```
/* Disabled state styling */
._retool-button-primaryButton[disabled],
._retool-button-primaryButton.disabled {
  opacity: 0.5 !important;
  cursor: not-allowed !important;
  background-color: #9CA3AF !important;
}

/* Loading state — Retool adds a loading spinner class */
._retool-button-primaryButton.loading {
  cursor: wait !important;
}

/* Table row hover */
._retool-table tbody tr:hover {
  background-color: #EEF2FF !important;
  cursor: pointer;
}

/* Input focus state */
._retool-textInput input:focus {
  border-color: #7C3AED !important;
  box-shadow: 0 0 0 3px rgba(124, 58, 237, 0.1) !important;
  outline: none !important;
}
```

**Expected result:** Interactive states (hover, focus, disabled) match your design system's specifications.

### 6. Handle components that resist styling

Some Retool components have deeply nested DOM structures or use Shadow DOM patterns that make CSS targeting difficult. The Date Picker, Select/Dropdown, and certain chart components fall into this category. For these, consider:

1. Use Inspector properties first — they often expose style options for the parts that matter
2. Add very specific CSS selectors found via DevTools inspection
3. For full control, replace with a Custom Component (iframe widget) that renders your own version

For components where some things style correctly but others don't, the Custom Component approach via RapidDev's Retool experts can save significant time when visual precision is critical.

```
/* Date Picker calendar popup styling example */
._retool-datePicker .ant-picker-panel {
  border-radius: 8px !important;
  box-shadow: 0 8px 24px rgba(0,0,0,0.12) !important;
}

._retool-datePicker .ant-picker-cell-selected .ant-picker-cell-inner {
  background-color: #7C3AED !important;
}

/* Select dropdown styling */
.ant-select-dropdown {
  border-radius: 8px !important;
  box-shadow: 0 4px 16px rgba(0,0,0,0.1) !important;
}
```

**Expected result:** Date picker and select dropdown popups display with rounded corners and custom shadows.

### 7. Create a reusable branding checklist

Efficiently brand multiple Retool apps by building a master CSS file in Preloaded CSS that covers all common component types. Then each new app automatically inherits the brand. Organize the CSS into sections: tokens/variables, buttons, tables, inputs, containers, typography, and responsive overrides.

Document each class name convention you create (e.g., .section-header, .danger-action, .mono-text) and share with your team so everyone applies classes consistently across apps.

**Expected result:** New Retool apps automatically use your brand colors, fonts, and component styles without any per-app CSS work.

## Complete code example

File: `Settings → Preloaded CSS (component customization system)`

```css
/* ================================================
   Retool UI Customization System — Preloaded CSS
   Covers: Buttons, Tables, Inputs, Containers, Typography
   ================================================ */

/* --- Design Tokens --- */
:root {
  --brand-primary: #7C3AED;
  --brand-primary-hover: #6D28D9;
  --brand-danger: #DC2626;
  --brand-success: #059669;
  --brand-warning: #D97706;
  --surface-bg: #F9FAFB;
  --surface-card: #FFFFFF;
  --border-color: #E5E7EB;
  --text-primary: #111827;
  --text-muted: #6B7280;
  --radius-sm: 6px;
  --radius-md: 8px;
  --radius-lg: 12px;
}

/* --- App Background --- */
._retool-app-body {
  background-color: var(--surface-bg) !important;
}

/* --- Buttons: Primary --- */
._retool-button-primaryButton {
  background-color: var(--brand-primary) !important;
  border-color: var(--brand-primary) !important;
  border-radius: var(--radius-md) !important;
  font-weight: 600 !important;
}
._retool-button-primaryButton:hover:not([disabled]) {
  background-color: var(--brand-primary-hover) !important;
  border-color: var(--brand-primary-hover) !important;
}

/* Danger button class */
.danger-action ._retool-button-primaryButton {
  background-color: var(--brand-danger) !important;
  border-color: var(--brand-danger) !important;
}

/* --- Tables --- */
._retool-table {
  border-radius: var(--radius-lg) !important;
  overflow: hidden !important;
  border: 1px solid var(--border-color) !important;
}
._retool-table thead tr {
  background-color: var(--surface-bg) !important;
}
._retool-table th {
  font-weight: 600 !important;
  font-size: 12px !important;
  text-transform: uppercase !important;
  letter-spacing: 0.05em !important;
  color: var(--text-muted) !important;
}
._retool-table tbody tr:hover {
  background-color: #EEF2FF !important;
}

/* --- Inputs --- */
._retool-textInput input:focus {
  border-color: var(--brand-primary) !important;
  box-shadow: 0 0 0 3px rgba(124,58,237,0.1) !important;
}

/* --- Containers --- */
._retool-container {
  border-radius: var(--radius-md) !important;
  background-color: var(--surface-card) !important;
  border-color: var(--border-color) !important;
}
```

## Common mistakes

- **Writing CSS rules before checking whether the Inspector already exposes the property you need** — undefined Fix: Always check the Inspector panel's Style/Appearance section first. Many properties (color, border radius, font size, padding) are directly configurable there with no CSS needed. CSS should be a last resort, not a first instinct.
- **Setting theme-level colors in the Theme Editor AFTER making individual Inspector overrides, and then wondering why the theme change doesn't affect those components** — undefined Fix: Inspector overrides take precedence over the Theme Editor. If you want theme changes to affect a component, remove any conflicting Inspector-level color/style overrides on that component first.
- **Using the same CSS Class Name across many apps without centralizing the CSS in Preloaded CSS** — undefined Fix: If you're assigning CSS Class Names like .danger-action or .card-header across multiple apps, put the corresponding CSS rules in Preloaded CSS rather than copy-pasting them into each app's Custom CSS.

## Best practices

- Always try Inspector properties and Theme Editor before writing CSS — they cover most customization needs without code
- Use the Theme Editor for organization-wide design tokens, app-level Custom CSS for app-specific overrides, and Preloaded CSS for org-wide baselines
- Create a naming convention for CSS Class Names and document it: .section-header, .danger-action, .mono-text, .hide-on-mobile
- Use CSS custom properties (variables) for brand colors so you can update the entire design system by changing one token value
- Test customizations in preview mode at multiple viewport sizes before deploying to users
- Keep a record of which ant- prefixed classes you use for dropdown/popup styling — these are less stable and may need updating after Retool upgrades
- For apps requiring deep visual customization, consider whether Retool Custom Components (iframe or React CLI) would be more maintainable than extensive CSS overrides

## Frequently asked questions

### Does Retool's Theme Editor affect all apps or just the current one?

The Theme Editor (accessed via App Settings → Appearance → Theme) affects only the current app. For org-wide style defaults, use Settings → Preloaded CSS/JS (accessible from the main Settings menu, not App Settings). Preloaded CSS applies to all apps in your Retool organization.

### Why do Inspector color settings sometimes get overridden by CSS?

CSS rules with !important override Inspector settings because they act at the browser rendering level. If you add a CSS rule like ._retool-button-primaryButton { background-color: red !important; }, it will override the Inspector's color setting for all buttons. Use CSS Class Names to scope rules to specific components and avoid unintended overrides.

### Can I create reusable component templates in Retool?

Not directly — Retool doesn't have a component template library. The closest approach is: use the Module feature to create a reusable sub-app with preconfigured components, or build a reference app with all your styled components and copy-paste from it into new apps. Components copy-paste with their Inspector settings intact, so this works reasonably well for teams.

---

Source: https://www.rapidevelopers.com/retool-tutorial/how-to-customize-ui-components-in-retool
© RapidDev — https://www.rapidevelopers.com/retool-tutorial/how-to-customize-ui-components-in-retool