ComfyUI Hidden & Flexible Inputs

ComfyUI Hidden & Flexible Inputs

Hidden Inputs

Hidden inputs are not shown in UI but automatically provided by ComfyUI.

Name	Type	Purpose
UNIQUE_ID	str	Node's unique ID
PROMPT	dict	Full prompt data
EXTRA_PNGINFO	dict	PNG metadata storage
DYNPROMPT	object	Dynamic prompt access

Usage in V3 Schema

class NodeWithHiddenInputs(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        return io.Schema(
            node_id="NodeWithHiddenInputs",
            category="utils",
            inputs=[
                io.Image.Input("image"),
                io.Hidden.unique_id(),
                io.Hidden.prompt(),
                io.Hidden.extra_pnginfo(),
                io.Hidden.dynprompt(),
            ],
            outputs=[io.Image.Output()],
        )

    @classmethod
    def execute(cls, image, unique_id=None, prompt=None,
                extra_pnginfo=None, dynprompt=None) -> io.NodeOutput:
        print(f"Node ID: {unique_id}")

        if extra_pnginfo is not None:
            extra_pnginfo["custom_data"] = {"key": "value"}

        return io.NodeOutput(image)

UNIQUE_ID: Per-Node State

class StatefulNode(io.ComfyNode):
    _states = {}

    @classmethod
    def execute(cls, image, unique_id=None) -> io.NodeOutput:
        if unique_id not in cls._states:
            cls._states[unique_id] = {"call_count": 0}
        cls._states[unique_id]["call_count"] += 1
        return io.NodeOutput(image)

EXTRA_PNGINFO: Metadata Writing

@classmethod
def execute(cls, image, metadata_key, metadata_value,
            extra_pnginfo=None) -> io.NodeOutput:
    if extra_pnginfo is not None:
        extra_pnginfo["custom_metadata"] = {metadata_key: metadata_value}
    return io.NodeOutput(image)

Flexible Inputs

Wildcard Type (Any Type)

class AnyTypePassthrough(io.ComfyNode):
    @classmethod
    def define_schema(cls):
        any_type = io.MatchType.Template("any")
        return io.Schema(
            node_id="AnyTypePassthrough",
            category="utils",
            inputs=[io.MatchType.Input("value", template=any_type)],
            outputs=[io.MatchType.Output(template=any_type)],
        )

    @classmethod
    def execute(cls, value) -> io.NodeOutput:
        return io.NodeOutput(value)

forceInput Option

io.Int.Input(
    "value",
    default=0,
    forceInput=True,  # Connection only, no widget
)

Important Rules

Hidden Inputs Need Default Values

# CORRECT
def execute(cls, image, unique_id=None, prompt=None):
    ...

# WRONG
def execute(cls, image, unique_id, prompt):
    ...

Always Check for None

@classmethod
def execute(cls, image, prompt=None, extra_pnginfo=None) -> io.NodeOutput:
    if prompt is not None:
        node_count = len(prompt)

    if extra_pnginfo is not None:
        extra_pnginfo["key"] = "value"  # OK to modify

    return io.NodeOutput(image)

Don't Modify PROMPT

# READ only
if prompt:
    node_count = len(prompt)

# DON'T modify
# prompt["new_node"] = {...}  # WRONG!

Best Practices

1. Only declare needed hidden inputs
2. Always check for None
3. PROMPT is read-only, EXTRA_PNGINFO is writable
4. Use UNIQUE_ID for per-node state