Theme
Version
GitHub PyPI Discord
On this page

Built-in tags

Citry provides these tags in every component template. You do not need to register or import them.

Control flow

<c-if>

Render a block when its cond expression is truthy. An <c-if> may be followed by any number of <c-elif> branches and one <c-else> branch.

<c-if cond="is_admin">
  <p>Administrator tools</p>
</c-if>

The control-flow guide covers inline c-if attributes, truthiness, and branch ordering.

<c-elif>

Add another condition to an <c-if> chain. Citry renders this branch only when every earlier condition was false and this branch's cond is truthy.

<c-if cond="is_admin">Admin</c-if>
<c-elif cond="is_editor">Editor</c-elif>

<c-else>

Add the final fallback to an <c-if> chain. <c-else> has no cond attribute.

<c-if cond="is_signed_in">Account</c-if>
<c-else>Sign in</c-else>

<c-for>

Repeat a block for every value in an iterable. Its each attribute uses a Python-style target and expression.

<c-for each="book in books">
  <p>{{ book.title }}</p>
</c-for>

Read Control flow for unpacking, filtering, and the loop helper.

<c-empty>

Show an empty state when the <c-for> immediately before it produces no items.

<c-for each="book in books">
  <p>{{ book.title }}</p>
</c-for>
<c-empty>No books yet.</c-empty>

Slots

<c-slot>

Mark a place where another template can add content. Leave out name for the default slot, or name the slot when a component has more than one. Content inside the tag is its fallback.

<article>
  <c-slot />
  <footer>
    <c-slot name="footer">No footer supplied.</c-slot>
  </footer>
</article>

See Slots for required slots, slot data, dynamic names, and fallback details.

<c-fill>

Choose which named slot receives a block of content when you use a component. You can pass plain body content when you only need the default slot.

<c-Panel>
  <c-fill name="footer">
    <a href="/help/">Get help</a>
  </c-fill>
</c-Panel>

Dynamic output

<c-component> built-in component

Render the component named by is in this tag's place.

is (required) is a registered component name or a Component class; every other attribute is passed to it as a kwarg, and the body (fills included) as its slots.

<c-element> built-in component

Render a plain HTML element whose tag name is the is value.

is (required) is the tag name; every other attribute becomes an HTML attribute of the element, and the body its children. Void elements (br, img, ...) reject a body.

Read Dynamic components for complete examples and the difference between component names and HTML tag names.

Data and resilience

<c-provide> built-in component

Provide data to the components rendered inside this tag.

key (required) names the data; all other attributes become the provided fields, injectable below as self.inject(key).<field>.

<c-cache> built-in component

Cache and replay one named transparent template region.

key is a required stable fragment name. vary contains every caller-dependent value that can change the body, ttl controls expiry, version selects an author-controlled invalidation family, and enabled=False bypasses caching. The body is not inspected or included in the key, and a hit emits no wrapper element.

<c-error-fallback> built-in component

Catch render errors in the wrapped content and show fallback content instead.

The guarded content is the tag body (the default slot). The fallback is the fallback attribute (a string), or the fallback fill, which receives the error as slot data (data.error).

Page assets

<c-css> built-in component

Marks where the collected stylesheet dependency tags are placed.

<c-js> built-in component

Marks where the collected <script> dependency tags are placed.

The JS and CSS dependencies guide explains collection, placement, and serialization strategies.

Literal template text

<c-raw>

Keep template-looking text unchanged. Citry does not evaluate expressions or component tags inside <c-raw>.

<c-raw>
  {{ this_stays_as_text }}
  <c-Card>This tag stays as text too.</c-Card>
</c-raw>