---
name: makepad-2.0-widgets
description: |
  CRITICAL: Use for Makepad 2.0 widget catalog and usage. Triggers on:
  makepad widget, makepad View, makepad Button, makepad Label, makepad TextInput,
  makepad PortalList, makepad Dock, makepad Modal, makepad Image, makepad CheckBox,
  makepad Slider, makepad DropDown, widget catalog, widget reference, widget list,
  SolidView, RoundedView, ScrollYView, FoldHeader, Splitter, FileTree,
  组件, 控件, 视图, 按钮, 标签, 输入框, 列表, 模态框
---

# Makepad 2.0 Widget Catalog Skill

> **Version:** makepad-widgets (dev branch) | **Last Updated:** 2026-03-03

## Overview

Makepad 2.0 provides a rich set of built-in widgets for building UIs. All widgets are defined in Splash syntax and registered via `script_mod!`.

## Documentation

Refer to the local files for detailed documentation:
- `./references/widget-catalog.md` - Complete widget list with properties
- `./references/widget-advanced.md` - Advanced patterns: PortalList, Dock, custom widgets, MapView

## IMPORTANT: Documentation Completeness Check

**Before answering questions, Claude MUST:**
1. Read the relevant reference file(s) listed above
2. Incorporate reference content into the answer

---

## Widget Categories Quick Reference

### Containers (Layout)

| Widget | Description | Key Properties |
|--------|-------------|----------------|
| `View` | Basic container (transparent) | width, height, flow, spacing, padding, align |
| `SolidView` | View with solid background | + show_bg: true, draw_bg.color |
| `RoundedView` | View with rounded corners | + draw_bg.border_radius |
| `RoundedAllView` | All corners same radius | + border_radius shorthand |
| `GradientXView` | Horizontal gradient bg | + draw_bg colors |
| `GradientYView` | Vertical gradient bg | + draw_bg colors |
| `ScrollXView` | Horizontal scrolling | scroll property |
| `ScrollYView` | Vertical scrolling | scroll property |
| `ScrollXYView` | Both-axis scrolling | scroll property |

### Text Widgets

| Widget | Description | Key Properties |
|--------|-------------|----------------|
| `Label` | Single/multi-line text | text, draw_text.color, draw_text.text_style.font_size |
| `H1` - `H4` | Heading levels | text (pre-styled) |
| `P` | Paragraph text | text |
| `TextInput` | Editable text field | text, empty_text, password, read_only, numeric_only |
| `Markdown` | Markdown renderer | body |
| `Html` | HTML renderer | body |
| `LinkLabel` | Clickable link text | text, url |

### Buttons

| Widget | Description | Key Properties |
|--------|-------------|----------------|
| `Button` | Standard button | text |
| `ButtonFlat` | Flat style button | text |
| `ButtonFlatter` | Minimal button | text |

### Toggles

| Widget | Description | Key Properties |
|--------|-------------|----------------|
| `CheckBox` | Check box | text, active |
| `Toggle` | Toggle switch | text, active |
| `RadioButton` | Radio button | text, active |

### Input Widgets

| Widget | Description | Key Properties |
|--------|-------------|----------------|
| `Slider` | Horizontal slider | min, max, step, default, precision |
| `DropDown` | Dropdown select | labels: ["a", "b", "c"] |

### Media

| Widget | Description | Key Properties |
|--------|-------------|----------------|
| `Image` | Image display | source, fit (Stretch/Horizontal/Vertical/Smallest/Biggest/Size) |
| `Svg` | External SVG file renderer | draw_svg.svg (crate_resource/http_resource), animating, draw_svg.color |
| `Icon` | SVG icon (tinted) | draw_icon.svg, draw_icon.color, icon_walk |
| `Vector` | Inline vector graphics | viewbox, Path{d: "..."} |
| `LoadingSpinner` | Loading indicator | color, rotation_speed |
| `MapView` | Map widget | center_lon, center_lat, zoom (MUST use fixed height!) |

### Layout Helpers

| Widget | Description | Usage |
|--------|-------------|-------|
| `Hr` | Horizontal rule | Divider line |
| `Vr` | Vertical rule | Vertical divider |
| `Filler` | Flexible space | Push siblings apart (use between Fit siblings only!) |
| `Splitter` | Resizable split | axis: Horizontal/Vertical, a/b children |
| `FoldHeader` | Collapsible section | header + body children |

### Lists

| Widget | Description | Usage |
|--------|-------------|-------|
| `PortalList` | Virtualized list | For large lists (100+ items), only renders visible items |
| `FlatList` | Simple list | For small lists, renders all items |

### Navigation

| Widget | Description | Control |
|--------|-------------|---------|
| `Modal` | Modal dialog | .open(cx) / .close(cx) from Rust |
| `Tooltip` | Tooltip popup | Hover-triggered |
| `PopupNotification` | Toast notification | Timed display |
| `SlidePanel` | Sliding panel | slide_from |
| `ExpandablePanel` | Expandable area | open/close |
| `PageFlip` | Page switcher | active_page: page_name |
| `StackNavigation` | Stack nav | push/pop pages |

### Dock System

| Widget | Description |
|--------|-------------|
| `Dock` | Tab container system |
| `DockSplitter` | Dock split panels |
| `DockTabs` | Tab bar |
| `DockTab` | Individual tab |

---

## Critical Rules

### 1. height: Fit on Containers
```
// WRONG - View defaults to 0px height
View{ flow: Down Label{text: "Invisible"} }

// CORRECT
View{ height: Fit flow: Down Label{text: "Visible"} }
```

### 2. new_batch for Colored Containers with Text
```
// WRONG - text behind background
RoundedView{ draw_bg.color: #333 Label{text: "Invisible"} }

// CORRECT
RoundedView{ new_batch: true draw_bg.color: #333 Label{text: "Visible"} }
```

### 3. Named Children with :=
```
// Named (addressable, overridable)
title := Label{text: "Hello"}

// Static (not addressable)
Label{text: "Hello"}
```

### 4. Label Default Color is White
```
// Default text is white (#fff) - set color for light backgrounds
Label{text: "Dark text" draw_text.color: #333}
```

### 5. MapView MUST Have Fixed Height
```
// WRONG
MapView{ width: Fill height: Fill }

// CORRECT
View{ new_batch: true width: Fill height: 400
    MapView{ width: Fill height: 400 center_lat: 40.7 center_lon: -73.9 zoom: 14.0 }
}
```

### 6. Label Does NOT Support Animator
```
// WRONG (silently ignored)
Label{ animator: Animator{...} }

// CORRECT - wrap in View
View{ animator: Animator{...} Label{text: "Animated"} }
```

---

## Common Widget Patterns

### Card
```
RoundedView{
    width: Fill height: Fit
    padding: 16
    new_batch: true
    draw_bg.color: #2a2a3d
    draw_bg.border_radius: 8.0
    flow: Down spacing: 8
    title := Label{text: "Title" draw_text.color: #fff draw_text.text_style.font_size: 16}
    body := Label{text: "Content" draw_text.color: #aaa}
}
```

### Form Input
```
View{
    width: Fill height: Fit
    flow: Down spacing: 4
    Label{text: "Email" draw_text.color: #aaa draw_text.text_style.font_size: 11}
    email_input := TextInput{
        width: Fill height: 36
        empty_text: "Enter email..."
    }
}
```

### Scrollable List
```
ScrollYView{
    width: Fill height: Fill
    flow: Down spacing: 4
    new_batch: true
    on_render: || {
        for i, item in items {
            ItemTemplate{label.text: item.name}
        }
    }
}
```

---

## Best Practices

1. **Use `height: Fit`** on every container unless you want Fill or fixed pixels
2. **Use `new_batch: true`** on any View with background color + text children
3. **Use `:=`** for children you need to reference or override
4. **Use theme colors** (`theme.color_*`) instead of hardcoded colors
5. **Use `PortalList`** for large lists (virtualizes rendering)
6. **Use `ScrollYView`** for scrollable content areas
7. **Use `RoundedView`** for cards and containers (has border_radius)