User guide

This guide shows how to build an app with ComposeUI. It explains each view and feature, and what each backend shows. To install ComposeUI and write a first window, read the README first. To see the features in complete apps, read the examples guide. To change ComposeUI itself, read the technical guide.

Building views is a complete app. The other examples show only the part of an app that a feature needs. A class name with a comment, such as study: StudyTree = attrs.Factory(StudyTree)  # a TreeView, stands for a view of your app of that kind. A record type, such as Run or Pipe, stands for an attrs class of your app.

A command such as uv run python -m examples.pipeform runs an example app. The examples are not in the package: run them from a clone of the repository (see Run an example).

Pages of this guide

• Core concepts

  • How ComposeUI maps to MVVM

  • Views are reactive

  • Signals inject arguments

• Building views

  • Define a view

  • child or Factory

  • Lay out views

  • Forms and their fields

  • Check a form

  • Compose views from mixins

  • The main view

    • A dashboard’s main view

    • The status bar

    • The app’s icon

    • Command-line options of your own

  • Structure an app

  • Saving and loading state

    • Versions of the state

• Widgets

  • Label

  • Buttons

  • Help on a form row

  • Text area

  • Integer input

  • Date input

  • File path input

    • Files on the server

    • Relative paths

  • Folder path input

  • Save path input

  • Slider

  • Progress bar

  • Metric

  • Log message

  • Expander

  • Tree

  • Markdown

  • Console

  • The File menu and picking a file

• Organizing the window

  • Pages

    • Page width

  • Tabs

  • Resizable panes

    • Panes one above the other

  • A list of views

  • Menus

  • Toolbars

  • Sidebar

  • Dialogs

    • Form dialogs

    • Content dialogs

    • Buttons and checks of a dialog

    • Replacing a file

• Tables

  • A table of records

    • Sorting and filtering

    • Widgets in cells

    • Paths by the row’s kind

    • How cells and headers look

  • A large table

    • Sorting and filtering a large table

    • Cells, selection, copy, and export

    • Rows in SQLite

    • Rows in a dataframe

• Charts

  • Kinds of chart

  • Log axes

  • Reference lines

  • Colors, fill, steps, and height

  • What each backend draws

  • Clicks on a chart

  • Report images

• Maps

  • Coordinates, points, and viewport

  • Tiles and network access

  • What each backend draws

• Running work in threads

  • Progress and canceling

  • Reusable loading tasks

    • Show a task’s state

    • Disable views while a task runs

  • How jobs behave

• A SQLite model

• Importing CSV data

  • A CSV table

  • CSV files

  • CSV URLs

  • CSV dialect detection

• Translating the app

  • Checking the catalogs

• Running the app

  • Backends

    • Adapt the views to the backend

  • Reloading the app on a change

  • Web backend

    • How the web differs from a window

    • Serve the app to other users

    • Deploy behind nginx

• Testing your app

  • Test the views

  • Test a component

  • Test a form

  • Test the jobs

  • Test with a model

  • Test on a backend

• Using a coding agent

  • Install the skill

  • Point the agent at the documentation