Skip to main content

Citry UI

Citry UI is Citry's own styled component library.

It gives you the building blocks for polished application interfaces without assembling a separate frontend component stack:

  • forms, navigation, dialogs, menus, feedback, layout, and data display;
  • accessible HTML with keyboard and pointer interactions;
  • useful server-rendered output before browser behavior starts;
  • consistent light and dark styling with theme variables and component parts;
  • built-in labels that applications can translate and override; and
  • Python composition alongside ordinary Citry template tags.

Browse the component catalog for current guides and API references.

Alpha release

Citry UI is in alpha.

Before Citry UI 1.0.0, a release may rename or remove components, inputs, template tags, CSS parts, or custom properties. Read the changelog and test the component states your application depends on before upgrading.

Installation

Install it on Python 3.11 through 3.15. It needs Citry 1.x (citry>=1.0.0,<2):

python -m pip install citry-ui

Usage

Register components with Citry.register_library():

import citry_ui
from citry import Citry, Component

app = Citry()
installed = app.register_library(citry_ui)

class Page(Component):
    citry = app
    template = """
      <main>
        <c-CButton type="submit">
          Save
        </c-CButton>
      </main>
    """

You can also directly import the components:

from citry_ui import CButton

button = CButton(
    loading=True,
    class_=["toolbar-action", {"is-prominent": True}],
    style={"inline-size": "100%"},
    slots={"default": "Save"},
)
rendered = button.render(citry=app)

See docs/design/ui_components/button.md.

Note: Calling str(button) or button.render() without citry=app raises LibraryComponentContextError.

Locales

To add selectable translations, named Citry UI format profiles, or browser-side locale switching, configure the catalog package that ships in this same wheel:

app = Citry(
    autodiscover=False,
    extensions_defaults={
        "i18n": {
            "source_locale": "en-US",
            "locales": ("en-US", "cs-CZ"),
            "catalogs": ("citry_ui_i18n", "my_app_i18n"),
        }
    },
)
app.register_library(citry_ui)

Place an application catalog after citry_ui_i18n to override selected public keys. Components render their initial strings on the server. Under a client-enabled <c-i18n> provider, stable Citry UI text and attributes follow locale changes through $c-tr, while values created by component JavaScript use the same provider through i18n.bind(). Explicit component label inputs or slots always win for that instance and are not replaced after a locale switch. Each component reference ends with a structured Translation keys table.

Subclassing

Advanced code can access or subclass the concrete class installed for this Citry instance:

import citry_ui
from citry import Citry, Component

app = Citry()
installed = app.register_library(citry_ui)
...
BoundButton = installed[CButton]

Development

Each family lives in one citry_ui/components/c*/ directory. Its runtime module owns its schemas, behavior, template, and CSS. components/__init__.py contains the only ordered definition catalog, and the package root combines it with ComponentLibrary. Citry owns materialization, registration rollback, invocation resolution, and installation records.

For editor completion and diagnostics without a host application, point the Citry VS Code setting directly at the same manifest:

{
  "citry.app": "citry_ui:__citry_library__"
}

Contributors can read the component-authoring guide for the specification and source-formatting rules.

Early-access feedback

Please report bugs, missing component states, accessibility problems, and API friction in the Citry issue tracker. Include the component name, Citry UI version, browser, and a small reproduction when possible.

Metadata

Release files for citry-ui 0.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for citry-ui 0.6.0
File Size Uploaded Provenance Actions
citry_ui-0.6.0.tar.gz 811.7 kB With provenance Details for citry_ui-0.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for citry-ui 0.6.0
File Interpreter ABI Platform Actions
citry_ui-0.6.0-py3-none-any.whl Python 3 none any Details for citry_ui-0.6.0-py3-none-any.whl

Total release size: 1.7 MB

Release files / citry_ui-0.6.0.tar.gz

Download URL citry_ui-0.6.0.tar.gz
Size 811.7 kB
Tags Source
SHA-256 checksum
How to use checksums
8a4e4553a41fbdbf4e11b2dafbc3e7cfbadb04845d7736813b2812adbd4fcc06
BLAKE2b-256 checksum
How to use checksums
c0678adfad13390d5863d3f0ce8aa928c1c38f5f6f1a79176e64b5d3a0147d3c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / citry_ui-0.6.0-py3-none-any.whl

Download URL citry_ui-0.6.0-py3-none-any.whl
Size 842.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d8edc7b746bb5687254ef04f5821e5b0e2e02ed3cea71f0164bff8b7482b6caa
BLAKE2b-256 checksum
How to use checksums
c17f3c50ffabbfd8e728190e629fb5fa19fb779ed18aeaaa143bc9ef3fd9e2e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for citry-ui 0.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for citry_ui-0.6.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page