Preview

Declare component previews and expose them only through CLI-owned servers.

Install with Citry(extensions=[PreviewExtension]). Components configure examples through a nested Preview class. Ordinary application adapters receive no routes from this extension.

on_extension_created(_ctx: OnExtensionCreatedContext) -> None

validate_config_fields(fields: Mapping[str, Any], component: type[Component] | None = None) -> None

on_component_class_created(ctx: OnComponentClassCreatedContext) -> None

file_path(component: type[Component] | None, field: str, path: str | Path) -> Path

previews(selection: Selection | None = None) -> tuple[_Preview, ...]

Declare one preview variant with metadata and component or template params.

One named example with display metadata and ordinary Python inputs.

Parameters

• slug str - Stable lowercase name, using letters, digits, and single hyphens.
• label str - Human-readable example label.
• description str - Plain-text explanation of the example.
• params Mapping[str, Any] - Inputs for the component or variables for its preview template.
• viewport Viewport | None - Optional browser dimensions overriding component defaults.

slug: str

label: str

description: str

params: Mapping[str, Any]

viewport: Viewport | None

Browser dimensions and pixel scale used to capture one variant.

Parameters

• width int - CSS width from 1 through 8192 pixels.
• height int - CSS height from 1 through 8192 pixels.
• device_scale_factor float - Finite pixel scale greater than zero, at most four.

width: int

height: int

device_scale_factor: float

Wrap preview content with one template or component class.

Exactly one source is required. The layout receives preview and a named content slot. Component classes must belong to the rendering app.

Parameters

• template str | None - Trusted inline Citry template source.
• template_file str | Path | None - UTF-8 template path relative to the declaring class.
• component type[Component] | None - Component class accepting preview metadata and content.

template: str | None

template_file: str | Path | None

component: type[Component] | None

A preview declaration, selection, or rendering request is invalid.

Display metadata for one component, without its live class or inputs.

id: str

name: str

group: str | None

Display metadata for one variant, without its Python params.

slug: str

label: str

description: str

viewport: Viewport

url: str

Component and variant metadata supplied to an example or variant layout.

component: PreviewComponent

variant: PreviewVariant

Variant metadata paired with lazily rendered content for a page layout.

variant: PreviewVariant

content: Slot

One component's metadata and ordered preview items.

component: PreviewComponent

items: tuple[PreviewItem, ...]

Ordered component groups supplied to a single-preview or gallery layout.

selection: Literal['variant', 'component', 'all']

components: tuple[PreviewGroup, ...]