makepad-widgets

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)