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.

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"}, [])

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.
Node		Anything a component may render: an element, None / False

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 module-attribute

Node = Union[Element, None, bool, Iterable[Any]]

Anything a component may render: an element, None / False for "nothing", or a (possibly nested) iterable of nodes.

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: Optional[str]) -> 'Element'

Return a copy of this element carrying key.

Handy when a factory result needs a key after the fact, for example while building a list comprehension over elements produced by a helper that doesn't take 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.