Slots

The slot value and fill types.

`Slot` class

Bases: Generic

Normalized slot content: a lazy, repeatable, standalone callable.

Construct it from a string, a function, a CitryElement, a ComponentLike, or a CitryRender. Calling the Slot returns a render part; str(slot) renders and serializes in one step. A standalone Slot containing a ComponentLike cannot resolve without an active component render.

Example

Slot("Hello!")                                # static content
Slot(lambda ctx: f"Hi {ctx.data.name}!")   # content function
Slot(Card(title="Hi"))                        # composed element

View source

`contents` attribute

The original value the Slot was created from.

View source

`component_name` attribute

Name of the component this slot content was given to (for debugging).

View source

`slot_name` attribute

Name of the slot this content fills (for debugging).

View source

`source_position` attribute

The (start, end) span of the <c-fill> in its template, if any.

View source

`extra` attribute

extra: dict[str, Any]

Scratch space for extensions to attach per-slot metadata.

View source

`content_func` attribute

content_func: SlotFunc[TSlotData]

The content function. Call the Slot itself instead of calling this directly.

View source

`SlotContext` class

Bases: Generic

The single argument a slot function receives.

Example

def my_slot(ctx: SlotContext) -> str:
    return f"Hello, {ctx.data.name}!"

View source

`data` attribute

data: TSlotData

Data passed to the slot by the <c-slot> tag (its extra attributes), or by the caller when the Slot is invoked directly. At runtime this is an immutable SlotData; the type parameter may describe a more precise component-specific field shape.

View source

`fallback` attribute

fallback: Slot | None

The slot's fallback content (the body of the <c-slot> tag), as a Slot.

None when the Slot is called directly, outside a <c-slot> site. Coerce it to a string (or render it via {{ fallback }}) to render the fallback.

View source

`provides` attribute

provides: Mapping[str, Any] | None

The provide/inject entries active where the Slot was invoked (the <c-slot> site or expression site). None when the Slot is called directly, outside a render. Template-defined fills use this so their bodies render with the invoking site's provides; a slot function may read it to inspect provided data.

View source

`SlotData` class

Bases: Mapping

Immutable data passed from a slot outlet to its fill.

Identifier-like keys are available as attributes, while every key remains available through mapping access. Keys beginning with an underscore and keys that collide with mapping methods intentionally require bracket access or fill-data destructuring.

Example

data = SlotData({"label": "Save", "aria-label": "Save item"})
data.label
data["aria-label"]

Parameters

values Mapping[str, Any] | None - The slot data values. Citry takes a shallow copy so later changes to the input mapping do not change a retained slot call.

View source

`SlotFunc` class

Bases: Protocol

The signature of a slot content function.

Example

def header(ctx: SlotContext) -> str:
    if ctx.data.get("name"):
        return f"Hello, {ctx.data.name}!"
    return str(ctx.fallback)

View source

`SlotInput` attribute

All forms in which slot content can be passed to a component.

Use this to type the fields of a component's Slots class::

class Table(Component):
    class Slots:
        header: SlotInput
        footer: SlotInput[FooterSlotData]

A field without a default must be filled whenever the component is used. A field annotated as SlotInput | None with a None default is optional. The required attribute on <c-slot> checks something different: it raises an error only if Citry renders that tag without content.

View source

`SlotResult` attribute

What a slot function may return.

A plain str is escaped when the slot renders; a SafeString or CitryRender is trusted and inlined as-is. A ComponentLike resolves against the Citry instance rendering the slot.