Theme
Version
GitHub PyPI Discord
On this page

Build with Citry

Welcome to Citry documentation!

Citry is the complete frontend stack for Python. From server-rendered HTML to browser behavior and back to a Python handler, one component holds all of it. No second application, no separate build.

New to Citry? Install Citry, then build your first component. The first component runs with plain Python, without setting up a web framework.

This documentation site is built with Citry too.

Getting started

Walk through this end-to-end tutorial. You begin with reusable server-rendered HTML, then add browser behavior, FastAPI, Python event handlers, server-side state, forms.

By the end of the tutorial you build an entire admin page containing a list of items and CRUD actions per row.

Follow it in order, or start with the part you need:

  1. Render components from Python: install Citry, build a component, and give it Python data.
  2. Build a page from smaller pieces: compose components and let them accept flexible content.
  3. Add behavior in the browser: use Alpine and connect parent and child components.
  4. Connect the browser to Python: serve the page with FastAPI, call Python from a click, keep State between calls, and handle forms.
  5. Update the page from Python: render into one part of the page and combine the patterns in a CRUD page.

The server-backed steps use FastAPI so they can show complete, runnable code. Citry also integrates with Django, Flask, Starlette, and other ASGI and WSGI applications.

Try it live

  • Playground - Write and render Python components in the browser.
  • Examples - Code-first cookbook. Copy or run in the browser.

Citry UI

Citry UI is Citry's first-party styled component library. It provides accessible buttons, fields, forms, tabs, dialogs, comboboxes, tables, and a theme you can adapt to your application.

Install the separate package:

uv add citry-ui

Then register Citry UI and choose a component from its catalog.

VSCode

Citry's VS Code extension brings:

  • Syntax highlight for Citry templates
  • Linting & diagnostics
  • Completion & hover information

Install the Citry extension, then add the language server to the same Python environment as the project:

python -m pip install citry-lsp

Follow the VS Code setup guide to connect the editor to your application. You can also run citry check from a terminal or CI, whether or not your editor has a dedicated Citry integration.

Learn more

  • Template syntax explains how to insert Python values, set HTML attributes from Python, show or repeat content, use built-in tags, and add Alpine behavior.
  • Components explains how component classes accept inputs, prepare template data, compose other components, and render HTML.
  • Registration explains how a component tag finds its Python class.
  • Slots shows how a component can accept whole pieces of HTML as content.
  • Client interactivity covers component browser data as Alpine variables, advanced setup with $component, $c-props, and browser communication between parents and children.
  • Server events covers Python handlers, State, forms, loading and error feedback, browser events, and page updates.
  • Web frameworks shows how to mount Citry in FastAPI, Starlette, Django, Flask, ASGI, or WSGI applications.
  • Troubleshooting starts from what went wrong and helps you find the likely cause.

When a project needs more control, read how to ship component JavaScript and CSS, return HTML fragments, cache rendered output, and test components.

Ready to build something? Install Citry and render your first component.