Theme
Version
GitHub PyPI Discord
On this page

Install and register Citry UI

To use Citry UI components such as <c-CButton> in your templates, install the package and register it once with Citry.

Working on Citry UI itself? See Develop Citry UI.

Install the package

Add citry-ui to your application:

uv add citry-ui

Register the library

Register Citry UI with the Citry instance that renders your components. Most applications use the default instance, citry:

import citry_ui
from citry import citry

citry.register_library(citry_ui)

Every component that renders through that instance can now use tags such as <c-CButton> and <c-CTabs>.

If your application creates its own instance, such as app = Citry(), call app.register_library(citry_ui) instead. A component uses the default instance unless it sets a citry class attribute to another one.

If a component renders through an instance that does not have the library, rendering fails with a NotRegistered error such as No component registered as 'cbutton'.

Write a component tag

Write the component's tag in a template:

from citry import Component

class SaveActions(Component):
    template = """
      <c-CButton type="submit">
        Save changes
      </c-CButton>
    """

Use components in Python

You can also import a component class, create it in Python, and pass it to a template:

from citry import Component
from citry_ui import CButton

save_button = CButton(
    type="submit",
    slots={"default": "Save changes"},
)

class SaveActions(Component):
    def template_data(self, kwargs, slots):
        return {"save_button": save_button}

    template = """
      <div>
        {{ save_button }}
      </div>
    """

Render a component alone

Inside a template, Citry renders save_button with the template's Citry instance. To render it on its own, pass the instance with citry=. Without it, Citry raises LibraryComponentContextError:

from citry import citry

html = str(save_button.render(citry=citry))