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 with Python 3.10 or newer. Needs citry>=0.6.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.3.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.3.0
File Size Uploaded Provenance Actions
citry_ui-0.3.0.tar.gz 742.9 kB With provenance Details for citry_ui-0.3.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.5 MB

Release files / citry_ui-0.3.0.tar.gz

Download URL citry_ui-0.3.0.tar.gz
Size 742.9 kB
Tags Source
SHA-256 checksum
How to use checksums
564abecb38d01593e921ef4b0681496de637bec621d10dad1f03b7dacc2d26af
BLAKE2b-256 checksum
How to use checksums
7c6665094a8182a9ca255bb27ba84aad9dc203baf83fb1e1e59d514f13c2a374
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 19, 2026.

Transparency log

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

Download URL citry_ui-0.3.0-py3-none-any.whl
Size 795.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
654464d44c63405c4360291d77d3c82061bd880db13cd6e9a1acc83ad6e4a867
BLAKE2b-256 checksum
How to use checksums
0f08bc699a2ca8a4e1114808ccd93051091410dcea1ccd5b1e3d99fb507b6200
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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 Oct 19, 2026.

Transparency log

Security for citry-ui 0.3.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.3.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 Oct 19, 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