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.7.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.4.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.4.0
File Size Uploaded Provenance Actions
citry_ui-0.4.0.tar.gz 796.3 kB With provenance Details for citry_ui-0.4.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.6 MB

Release files / citry_ui-0.4.0.tar.gz

Download URL citry_ui-0.4.0.tar.gz
Size 796.3 kB
Tags Source
SHA-256 checksum
How to use checksums
d2b0455c25aabe09d8d5050635764cc4dac13d9f900ec1a5b4175d78e66718ce
BLAKE2b-256 checksum
How to use checksums
f53278ad7c027fd87b8cb8b95f54f5c68bca3ff7b19107c217e41afe359cbc34
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 2, 2026.

Transparency log

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

Download URL citry_ui-0.4.0-py3-none-any.whl
Size 835.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
a6462c7e46b028fdd94e6e986b0fd9b77c8b39b5a4c50a93d960cabc33d9302e
BLAKE2b-256 checksum
How to use checksums
3f4793a174b96320666ec82b3031b9327ea83152aedd4b4c1cfa86b49489588c
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 2, 2026.

Transparency log

Security for citry-ui 0.4.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.4.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 2, 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