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 Conditions and loops for unpacking, filtering, and variable scope.

<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). Ordinary fallback strings are escaped; use the fill when the fallback needs markup.

Internationalization

<c-i18n> built-in component

Set locale context below this tag and optionally render a semantic host.

Use it to provide a locale to one subtree. Add a real tag when the subtree needs lang and dir, or enable its browser service with the bare client attribute. See Locales and context and Browser i18n.

<c-trans> built-in component

Render escaped translated text with application-owned named fills.

Use it when a translator needs to position an application-owned link or inline component. See Rich messages.

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 Asset placement guide explains where Citry puts the collected files and component assets.

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>

Read Comments and literal text for the trust boundary and exact raw-block rules.