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 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>=0.9.0:

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.5.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.5.0
File Size Uploaded Provenance Actions
citry_ui-0.5.0.tar.gz 805.5 kB With provenance Details for citry_ui-0.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.6 MB

Release files / citry_ui-0.5.0.tar.gz

Download URL citry_ui-0.5.0.tar.gz
Size 805.5 kB
Tags Source
SHA-256 checksum
How to use checksums
1476d67b6d11f78b6d0a6cad71191c52dee840f3ea7643ceffab747e89c61919
BLAKE2b-256 checksum
How to use checksums
fa57ac0ae2a961555163f5f4016f0e27ae5d0e8c28477fa24d91328a6f0fee1a
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.5.0-py3-none-any.whl

Download URL citry_ui-0.5.0-py3-none-any.whl
Size 841.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
424d46d1b4bbb0d9c8ec86c5c59f4830e0d3036467363407d694953977a333ff
BLAKE2b-256 checksum
How to use checksums
94496ad84fac906cb4c950ee4e5df4db745c3e06fb53ea2a82251103b8b020f0
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.5.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.5.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