/comfyui-node-inputs

name: comfyui-node-inputs
description: ComfyUI node input types - INT, FLOAT, STRING, BOOLEAN, COMBO widgets, hidden inputs, optional inputs, lazy inputs, force_input. Use when configuring node inputs, adding widgets, or customizing input behavior.

ComfyUI Node Inputs

Inputs define what data a node accepts. Widget inputs create UI controls; connection inputs create socket slots.

Widget Input Types

INT

io.Int.Input("seed",
    default=0,
    min=0,
    max=0xffffffffffffffff,
    step=1,
    control_after_generate=True,  # adds increment/decrement/randomize control
    display_mode=io.NumberDisplay.number,  # "number", "slider", or "gradient_slider"
    tooltip="Random seed for generation",
)

**NumberDisplay options**: `io.NumberDisplay.number`, `io.NumberDisplay.slider`, `io.NumberDisplay.gradient_slider`

**ControlAfterGenerate options**: `True` (default randomize), or `io.ControlAfterGenerate.fixed`, `.increment`, `.decrement`, `.randomize`. A mode value is treated as the control's *starting mode* only from frontend v1.57.0 (#19867); older frontends used the string as the control widget's name.

FLOAT

io.Float.Input("strength",
    default=1.0,
    min=0.0,
    max=10.0,
    step=0.01,
    round=0.001,         # rounding precision
    display_mode=io.NumberDisplay.slider,
    gradient_stops=[{"offset": 0.0, "color": [0, 0, 0]}, {"offset": 1.0, "color": [255, 255, 255]}],  # for gradient_slider mode
    tooltip="Effect strength",
)

STRING

# Single-line string
io.String.Input("name",
    default="",
    placeholder="Enter name...",
)

# Multi-line text area
io.String.Input("prompt",
    multiline=True,
    default="",
    placeholder="Enter prompt...",
    dynamic_prompts=True,  # enable dynamic prompt syntax
)

BOOLEAN

io.Boolean.Input("enabled",
    default=True,
    label_on="Enabled",
    label_off="Disabled",
    tooltip="Toggle this feature",
)

COMBO (Dropdown)

io.Combo.Input("mode",
    options=["option_a", "option_b", "option_c"],
    default="option_a",
    tooltip="Select processing mode",
    control_after_generate=True,  # adds increment/decrement/randomize control
)

**Combo with Enum**:

from enum import Enum

class BlendMode(Enum):
    NORMAL = "normal"
    MULTIPLY = "multiply"
    SCREEN = "screen"

io.Combo.Input("blend", options=BlendMode, default=BlendMode.NORMAL)
# Enum values auto-converted to string list

**Combo with file upload**:

io.Combo.Input("image_file",
    options=[],
    upload=io.UploadType.image,          # .image, .audio, .video, .model (for generic file upload)
    image_folder=io.FolderType.input,    # .input, .output, .temp
)

**Dynamic combo with remote options**:

io.Combo.Input("model_name",
    options=[],
    remote=io.RemoteOptions(
        route="/internal/models/checkpoints",
        refresh_button=True,
        control_after_refresh="first",  # "first" or "last"
        timeout=5000,        # ms
        max_retries=3,
        refresh=60000,       # TTL refresh interval in ms
    ),
)

**Security**: treat combo / `DynamicCombo` values as untrusted when they reach the filesystem. Re-validate any value used as a file/folder name, path, format or extension at the load/save boundary (`folder_paths.get_full_path_or_raise(...)`, `folder_paths.is_within_directory(base, path)`, or a fixed allowlist) — prompts can be submitted via the API with values outside `options`.

MULTICOMBO (Multi-select Dropdown)

io.MultiCombo.Input("tags",
    options=["tag1", "tag2", "tag3", "tag4"],
    default=["tag1"],
    placeholder="Select tags...",
    chip=True,  # display as chips
)
# Value type: list[str]

COLOR (Color Picker)

io.Color.Input("color",
    default="#ffffff",
    socketless=True,  # widget only by default
)
# Value type: str (hex color)

COLORS (Color Palette)

io.Colors.Input("palette",
    default=["#ff0000", "#00ff00"],
    socketless=True,
)
# Value type: list[str] (hex colors)

BOUNDING_BOX (Rectangle Selector)

io.BoundingBox.Input("region",
    default={"x": 0, "y": 0, "width": 512, "height": 512},
    socketless=True,
    component="my_component",  # optional custom UI component name
    force_input=False,
)
# Value type: {"x": int, "y": int, "width": int, "height": int}

BOUNDING_BOXES (Multiple Regions)

io.BoundingBoxes.Input("regions",
    default=[],
    socketless=True,
)
# Value type: list of {"x": int, "y": int, "width": int, "height": int, "metadata": dict}

CURVE (Spline Editor)

io.Curve.Input("curve",
    default=[(0.0, 0.0), (1.0, 1.0)],  # linear ramp
    socketless=True,
)
# Value type: raw curve data; normalize with CurveInput.from_raw(value)
# (from comfy_api.input import CurveInput)

RANGE (Levels/Range Editor)

io.Range.Input("levels",
    default={"min": 0.0, "max": 1.0},
    gradient_stops=None,     # gradient background for the slider
    show_midpoint=True,      # gamma midpoint handle
    value_min=0.0,
    value_max=1.0,
)
# Value type: raw dict; normalize with RangeInput.from_raw(value)
# (from comfy_api.input import RangeInput) -> .min_val, .max_val, .midpoint, .to_lut()

WEBCAM (Camera Capture)

io.Webcam.Input("capture")
# Value type: str

IMAGECOMPARE (Comparison Widget)

io.ImageCompare.Input("comparison", socketless=True)
# Value type: dict

Newer editor widgets (v0.31–v0.40, need a matching frontend)

io.VideoEdit.Input("trim", features=["trim"])   # "trim" and/or "crop" (default both)
# Value: {"trim": {"start_time": float, "duration": float}, "crop": {"x","y","width","height"}}
#   apply with video.as_trimmed(...) / video.as_cropped(...); zero width/height = full frame
io.ResolutionPreview.Input("preview",            # live preview of a computed size; optional by default
    ratio_