Theme
Version
GitHub PyPI Discord
On this page

Build with Citry

Citry is a fully typed frontend framework for Python with server events and Vue. One component holds its server-rendered HTML, browser behavior, CSS, translations, and Python event handlers. No second frontend application or separate build. It is inspired by Vue and Livewire.

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

This documentation site is built with Citry too.

Follow the tutorial

Watch the 50-minute Citry and Django code-along on YouTube

The tutorial starts with reusable HTML rendered in Python. Each step adds one thing: browser behavior, a FastAPI server, Python event handlers, values kept between calls, and forms. By the end, you have an admin page that lists items and lets you edit each 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 add slots for flexible content.
  3. Add behavior in the browser: use Vue and connect parent and child components.
  4. Connect the browser to Python: serve the page with FastAPI, call Python from a click, keep values between calls, and handle forms.
  5. Update the page from Python: replace a component with new HTML and combine the patterns in a CRUD page.

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

Try Citry in the browser

  • Playground: write Python components and render them in the browser.
  • Examples: copy a working recipe or run it in the browser.

Learn in depth

  • Template syntax explains how to insert Python values, set HTML attributes from Python, show or repeat content, use built-in tags, and add Vue behavior.
  • Components explains how a component accepts inputs, computes the values its template uses, uses other components, and renders HTML.
  • Registration explains how Citry finds the Python class behind a component tag.
  • Slots shows how a component can accept whole pieces of HTML as content.
  • Vue in Citry shows how to give a component data and methods in the browser, and how parent and child components talk to each other there.
  • Server events shows how a click or form submit calls Python, and covers values kept between calls, forms, loading and error feedback, 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 JS and CSS, return HTML fragments, make rendering faster, including caching rendered output, and test components.

Use Citry UI

Citry UI is Citry's own library of styled components. 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.

Set up VS Code

Install Citry from the Visual Studio Marketplace to add:

  • Syntax highlighting for Citry templates
  • Linting and diagnostics
  • Completion, hover information, and navigation
  • Safe formatting for inline templates, JavaScript, and CSS

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 extension to your application. You can also run citry check from a terminal or CI, whatever editor you use.

Find reference and help

  • Reference: Python, template, and browser APIs.
  • Getting help: ask questions or report a problem.
  • Release notes: what changed, and migration guides.
  • Compatibility: supported Python versions, operating systems, and more.
  • Security: template expressions, State, browser data, and what you must secure when you deploy.
  • Benchmarks: how fast Citry renders, and how early it reports common mistakes.

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