mesop

Mesop uses Python decorators (@component, @content_component, @web_component) to define UI components as pure Python functions, eliminating the need for HTML/CSS/JavaScript. The framework translates decorated Python functions into a component tree that gets serialized to protobuf (ui.proto) and sent to the browser for rendering. This approach leverages Python's function decorator pattern to create a declarative UI DSL where component composition happens through nested function calls.

Mesop implements a server-driven architecture where the Flask server (mesop/server/server.py) maintains a render_loop() that regenerates the entire UI component tree in response to user events. Events are captured by the browser client, sent via WebSocket to the server, processed by event handlers in the context, and the updated component tree is serialized and sent back to the client for re-rendering. This eliminates client-side state management complexity by centralizing all logic on the server.

Mesop provides command-line tools (mesop/bin/bin.py) for scaffolding new projects, running the development server, and building for production. The CLI includes commands like 'mesop run' to start the development server with hot reloading, and scaffolding scripts (scripts/scaffold_component.py) to generate boilerplate for new components. This tooling reduces setup friction and provides a standardized development workflow.

Mesop provides a styling system (mesop/component_helpers/style.py) that allows developers to apply CSS styles to components via Python objects. Components accept a 'style' parameter that takes a Style object with properties like width, height, color, etc. The framework converts these Python style objects to CSS and applies them to the rendered HTML. This approach provides type-safe styling without writing raw CSS, though developers can still use CSS classes for more complex styling.

Mesop includes built-in support for integrating with LLMs (Large Language Models) for AI-powered applications. The framework provides utilities for streaming LLM responses, handling token counting, and managing conversation history. This is documented in the AI Integration guide and enables developers to build chatbots, code assistants, and other AI applications using Mesop's UI components with LLM backends. Integration is typically done via standard LLM APIs (OpenAI, Anthropic, etc.) called from event handlers.

Mesop leverages Python type hints to provide type safety for component props. Components are defined as Python functions with typed parameters, and the framework validates props at runtime. This approach provides IDE autocomplete, type checking via mypy, and runtime validation without requiring a separate schema language. The type information is also used to generate the protobuf schema for client-server communication.

Mesop uses Python dataclasses decorated with @stateclass to define application state that persists across events within a user session. The runtime (mesop/runtime/runtime.py) creates and manages a context for each session that holds instances of these state classes. When events occur, handlers can mutate state directly (e.g., state.counter += 1), and the framework automatically detects changes and triggers re-rendering. State is stored in-memory on the server and tied to the WebSocket connection lifecycle.

Mesop's development workflow includes hot reloading (mesop/runtime/runtime.py) that watches Python source files for changes and automatically reloads the application without losing session state. When a file changes, the runtime re-imports the module, re-registers components, and triggers a re-render of the current page. This is implemented via file watchers and Flask's development server, allowing developers to see changes instantly without manual browser refresh.

Mesop uses Protocol Buffers (ui.proto) to serialize the component tree and send it from the server to the browser via WebSocket. The component tree is defined in Python on the server, converted to protobuf messages, and transmitted to the client where a TypeScript renderer (type_to_component.ts) deserializes and renders the components as HTML/CSS. This approach provides type safety, efficient binary serialization, and a clear contract between server and client.

Mesop provides a library of pre-built components (button, text, input, select, datepicker, etc.) that are styled with Material Design principles and wrapped as Python functions. These components are defined in mesop/components/ and automatically registered with the runtime. Developers can use these components by calling Python functions (e.g., mesop.button(label='Click me', on_click=handler)), which generates the appropriate protobuf messages for rendering. The component library is extensible — developers can create custom components using @component decorator.

Mesop supports integration of custom Web Components (HTML Custom Elements) via the @web_component decorator. This allows developers to wrap existing JavaScript libraries or custom HTML elements and use them alongside Python-defined components. The framework handles the serialization of props to the Web Component and event propagation back to Python event handlers. This is implemented via the type_to_component.ts renderer which has special handling for web components.

Mesop includes built-in support for running in Google Colab notebooks (mesop/colab_integration.py, notebooks/mesop_colab_getting_started.ipynb). When running in Colab, Mesop automatically configures the Flask server to use Colab's tunneling mechanism (ngrok or similar) to expose the UI to the browser. This allows developers to build and test interactive Mesop applications directly in Colab cells without setting up a local development environment.

Mesop components accept event handler functions (on_click, on_change, on_submit, etc.) that are automatically bound to user interactions. When an event occurs in the browser, it's serialized and sent to the server, where the runtime's context system (mesop/runtime/context.py) executes the handler function with the current session state automatically injected. Handlers can mutate state directly, and the framework detects changes and triggers re-rendering. This eliminates manual state passing and context threading.

Mesop provides @content_component decorator for creating components that can accept and render child elements. This enables composition patterns where parent components wrap child components (e.g., a Box component that contains buttons and text). The framework handles the serialization of child components into the parent's component tree. This is implemented via the component tree structure in mesop/runtime/context.py where components can have a 'children' property.