Mesop

Use this skill to build, debug, and deploy Mesop applications. Mesop is a Python-native UI framework that enables developers to build web apps without writing frontend code (HTML/CSS/JS).

Quick Triage

Use this skill for pure Python web UIs, especially for AI/ML demos and internal tools.
Do NOT use this skill if the user specifically requests a different Python framework (Streamlit, Gradio, Solara) unless they are asking for a comparison or migration.
Do NOT use this skill for general Flask/FastAPI backend development unless it's specifically about mounting a Mesop app.

Workflow

Setup: Install
```
mesop
```
and create
```
main.py
```
.
Define Page: Use
```
@me.page(path="/")
```
to define the entry point.
Define State: Create a
```
@me.stateclass
```
to hold session state (must be serializable).
Create Components: Build the UI tree using
```
me.box
```
,
```
me.text
```
,
```
me.input
```
, etc.
Handle Events: Write event handler functions (regular or generator) to update state.
Style: Apply styles using
```
me.Style
```
(flexbox/grid) for layout and appearance.
Deploy: Deploy to Cloud Run, Docker, or Hugging Face Spaces.

Essential Patterns

Standard Import

Always use the standard alias:

python

import mesop as me
import mesop.labs as mel # For labs components like chat

State Management

State is session-scoped and must be serializable.

python

@me.stateclass
class State:
  count: int = 0
  input_value: str = "" # Immutable default
  # items: list[str] = field(default_factory=list) # Mutable default pattern

Accessing State:

state = me.state(State)

inside components or event handlers.

Event Handlers

Regular: Run to completion, then update UI.
Generator:
```
yield
```
to stream UI updates (e.g., loading states, LLM streaming). MUST yield at the end.
Async: Use
```
async def
```
and
```
await
```
for concurrent operations.

Component Composition

Use

with

blocks for content components (parents):

python

with me.box(style=me.Style(display="flex")):
  me.text("Child 1")
  me.button("Child 2")

Key Usage

Use

key

to identify components for:

Resetting state (change key to re-render)
Focus management (
```
me.focus_component
```
)
Scroll targeting (
```
me.scroll_into_view
```
)
Reusing event handlers (access
```
e.key
```
)

Common Pitfalls

Closure Variables: Do NOT rely on closure variables in event handlers; they may be stale. Use
```
key
```
or state instead.
Input Race Conditions: Avoid setting
```
value
```
on inputs unless necessary. Use
```
on_blur
```
instead of
```
on_input
```
for performance, or track "initial" vs "current" value if bidirectional binding is needed.
Mutable Defaults: Never use mutable types (list, dict) as default values in
```
@me.stateclass
```
. Use
```
dataclasses.field(default_factory=...)
```
.
Global State: Global variables are shared across ALL users. Use
```
@me.stateclass
```
for per-session state.

Reference Map

Core Patterns:
```
references/core-patterns.md
```
(State, Events, Streaming, Navigation)
Components:
```
references/components-reference.md
```
(API reference for all components)
Styling & Layouts:
```
references/styling-and-layouts.md
```
(CSS-in-Python, Flexbox, Grid, Theming)
Deployment:
```
references/deployment-and-config.md
```
(Cloud Run, Docker, Config, Security)
Web Components:
```
references/web-components.md
```
(Custom JS integration, Lit)

mesop

NPX Install

Tags

SKILL.md Content

Mesop

Quick Triage

Workflow

Essential Patterns

Standard Import

State Management

Event Handlers

Component Composition

Key Usage

Common Pitfalls

Reference Map