Element¶

Immutable descriptor for a single node in PythonNative's virtual view tree. Element instances are produced by the component factories and consumed by the Reconciler.

You almost never construct an Element by hand; the factory functions exist precisely so app code stays in plain Python.

Node is the type of anything that can appear in a tree: an element, None or a bool for "nothing", or a (possibly nested) iterable of nodes. Built-in containers take *children: pn.Node, and components return pn.Node. Element.with_key returns a keyed copy, the typed way to key a user component.

Lightweight element descriptors for the virtual view tree.

An Element is an immutable description of a UI node, analogous to a React element. It captures a type, a read-only property snapshot, and an immutable sequence of children without creating any native platform objects. The reconciler consumes these trees to determine what native views must be created, updated, or removed.

An element's type is one of three things:

a str naming a native view ("Text", "View", ...),
a Component produced by @component, or
a structural type: one of the singletons defined here (FRAGMENT, ERROR_BOUNDARY, SUSPENSE) or a Context (whose elements are providers).

Structural types are real objects rather than magic strings so the reconciler can dispatch on them with identity checks and no user element can collide with them.

Elements are produced by built-in factories such as Text, Button, and Column, or by calling components.

Example

from pythonnative import Element

node = Element("Text", {"text": "Hello"}, [])

Type Aliases:

Name	Description
`Node`	Anything that can appear in an element tree.

Classes:

Name	Description
`StructuralType`	Identity object naming a reconciler-owned element kind.
`Element`	Immutable description of a single UI node.

Functions:

Name	Description
`type_label`	Return a human-readable name for an element type (for messages).

Attributes:

Name	Type	Description
`FRAGMENT`		Type of `Fragment` elements: a transparent group.
`ERROR_BOUNDARY`		Type of `ErrorBoundary` elements.
`SUSPENSE`		Type of `Suspense` elements.

FRAGMENT `module-attribute` ¶

FRAGMENT = StructuralType('Fragment')

Type of Fragment elements: a transparent group.

ERROR_BOUNDARY `module-attribute` ¶

ERROR_BOUNDARY = StructuralType('ErrorBoundary')

Type of ErrorBoundary elements.

SUSPENSE `module-attribute` ¶

SUSPENSE = StructuralType('Suspense')

Type of Suspense elements.

Node ¶

Node = (
    Element
    | None
    | bool
    | list[Node]
    | tuple[Node, ...]
    | Iterator[Node]
)

Anything that can appear in an element tree.

An element, None or a bool for "nothing" (so cond and pn.Text(...) and pn.Text(...) if cond else None both work), or a possibly nested list, tuple, or iterator (a generator expression) of nodes. The alias names those containers rather than Iterable so a bare string, which is an iterable of strings, is a type error. Every built-in container declares *children: Node and component bodies return a Node. Strings aren't nodes: wrap text in Text.

StructuralType ¶

StructuralType(name: str)

Identity object naming a reconciler-owned element kind.

Instances are singletons compared by identity; repr shows the kind for debugging (<Fragment>).

Element `dataclass` ¶

Element(
    type_: Any,
    props: Optional[Mapping[str, Any]] = None,
    children: Optional[Iterable[Any]] = None,
    key: Optional[str] = None,
)

Immutable description of a single UI node.

Built-in elements use a string type ("Text", "Button", "Column", etc.); components use the Component object itself as type; structural elements use a StructuralType or a Context. The reconciler dispatches on this distinction when mounting the tree.

Attributes:

Name	Type	Description
`type`	`Any`	The element kind (see the module docstring).
`props`	`Mapping[str, Any]`	Read-only snapshot of properties passed to the native handler or the component function.
`children`	`tuple[Any, ...]`	Immutable tuple of child nodes. `None` and `False` entries are permitted and dropped during reconciliation, so conditional children (`cond and Text(...)`) need no special casing. Components receive these as their `*children`.
`key`	`Optional[str]`	Optional stable identity used by the reconciler when diffing keyed lists. Two elements with the same `type` and `key` are treated as the same logical node across renders.

Methods:

Name	Description
`with_key`	Return a copy of this element carrying `key`.

with_key ¶

with_key(key: object) -> 'Element'

Return a copy of this element carrying key.

This is the typed way to key a user component, whose call signature can't include key= (PEP 612 forbids keyword parameters next to a ParamSpec):

pn.Column(*(Row(item).with_key(item.id) for item in items))

Built-in factories also accept key= directly. Non-string keys are converted with str; None clears the key.

type_label ¶

type_label(type_obj: Any) -> str

Return a human-readable name for an element type (for messages).

Next steps¶

See how trees of elements get mounted in Reconciliation.
Browse the built-in element types in Components.