ComfyUI Node

XController

A knob, a fader, a button, a toggle — one node that's all of them

By Xz3r0-M·Created 8 months ago·Updated about 6 hours ago· 13
XController
    • FLOAT
    • INT
    • BOOLEAN
    • X
    • Y
    control_typeKnob
    value_modeRange
    min0.00
    max1.00
    step0.010
    default_value0.50
    steps[0.0, 0.25, 0.5, 0.75, 1.0]
    default_step_index2
    base_value100.00
    pct_min-50.0
    pct_max50.0
    default_pct0.0
    shapecircle
    toggle_styleswitch
    default_statetrue
    button_modeincrease
    button_stylerounded
    x_min0.00
    x_max1.00
    x_step0.010
    x_default0.50
    y_min0.00
    y_max1.00
    y_step0.010
    y_default0.50
    crosshair_visibletrue
    grid_visibletrue
    _normalized0.5000
    _statefalse
    _x_normalized0.5000
    _y_normalized0.5000

    ComfyUI ships a Primitive node for feeding numbers into a graph, but "feed a number" and "have a physical knob to turn" are different feelings. XController is the pack's answer to the second one: one node that renders as a Knob, a horizontal or vertical fader, a Toggle switch, a hold Button, or an XY Pad - your pick via a dropdown. You get real, saved control widgets that drive anything with a numeric input, which is a much nicer way to scrub a denoise strength or CFG than typing into a box.

    How it works

    Pick control_type and the node re-renders itself as that widget. All the configuration is done through hidden, socketless widgets that the frontend draws for you, so the node looks like a control surface rather than a wall of sliders. The outputs are what you wire downstream:

    • FLOAT - the current value of any analog control.
    • INT - the FLOAT truncated toward zero, for the integer-input nodes.
    • BOOLEAN - current state, for Toggle and Button.
    • X and Y - the two coordinates, for the XY Pad.

    value_mode decides how a 0–1 widget position becomes a FLOAT output:

    • Range - mapped between min and max, with step snapping (set step to 0 to disable snap).
    • Steps - snapped to the nearest entry in a JSON array, default [0.0, 0.25, 0.5, 0.75, 1.0].
    • Percentage - a base value with a percentage offset range, e.g. base_value 100 with ±50%.

    The Button is the fiddly one: button_mode picks Increase, Decrease or Toggle behavior, it moves one step per repeat, and it reports "is it being held" on BOOLEAN. The Toggle flips BOOLEAN and emits 0 or 1 on FLOAT. XY Pad gets its own x_min/x_max/x_step and y_* twins, plus crosshair_visible and grid_visible for aiming.

    Everything has a sensible default and a reset/start value, so a workflow loads into the position it was saved at. The node is marked not idempotent - its output is genuinely "whatever the control currently says," not a cached value.

    Installing it

    XController ships in ComfyUI-Xz3r0-Nodes (by Xz3r0-M), found under ♾️ Xz3r0/Workflow-Processing. ComfyUI Manager: search ComfyUI-Xz3r0-Nodes and install. Manual:

    cd ComfyUI/custom_nodes
    git clone https://github.com/Xz3r0-M/ComfyUI-Xz3r0-Nodes.git
    cd ComfyUI-Xz3r0-Nodes
    pip install -r requirements.txt
    

    Restart ComfyUI after. No model files, no GPU cost - this one is pure UI. It does depend on the pack's frontend JS, so if you're on an ancient ComfyUI the custom widget may not render; update ComfyUI before filing a bug.

    Gotchas

    The steps field is a literal JSON array - write [0, 0.25, 0.5, 1], not 0,0.25,0.5,1, or the node falls back to [0, 1]. And remember the INT output is truncation toward zero, not rounding, so a FLOAT of 3.9 becomes 3. For most people the honest take is: this is the node you reach for when you want to actually feel a parameter, and a plain Primitive when you don't. Not a workflow-critic, but the one I'd grab for an interactive demo.

    Category♾️ Xz3r0/Workflow-Processing

    Inputs (31)

    NameTypeDefaultDescription
    control_typeCOMBOKnobSelect the visible controller: Knob, horizontal fader, vertical fader, Toggle, hold Button, or XY Pad.
    value_modeCOMBORangeControls how a 0-1 position becomes FLOAT output: Range, Steps, or Percentage.
    minFLOAT0.00Lowest FLOAT output in Range mode.
    maxFLOAT1.00Highest FLOAT output in Range mode.
    stepFLOAT0.010Range snap size and hold-button increment. Use 0 to disable snapping.
    default_valueFLOAT0.50Default Range value used as the intended reset/start value.
    stepsSTRING[0.0, 0.25, 0.5, 0.75, 1.0]JSON array of discrete FLOAT outputs, for example [0, 0.25, 0.5, 1].
    default_step_indexINT2Default step index, starting at 0. The button moves one index per repeat.
    base_valueFLOAT100.00Base value used before applying the percentage offset.
    pct_minFLOAT-50.0Minimum percentage offset. Negative values reduce the base value.
    pct_maxFLOAT50.0Maximum percentage offset. Positive values increase the base value.
    default_pctFLOAT0.0Default percentage offset used as the intended reset/start value.
    shapeCOMBOcircleVisual shape for knobs, or handle shape for horizontal/vertical faders.
    toggle_styleCOMBOswitchVisual style of the boolean toggle. It changes BOOLEAN and outputs 0 or 1 on FLOAT.
    default_stateBOOLEANtrueDefault boolean state for Toggle when no saved state exists.
    button_modeCOMBOincreaseIncrease: hold to raise value. Decrease: hold to lower value. Toggle: click between min and max
    button_styleCOMBOroundedVisual shape of the hold button. The button also reports pressed state on BOOLEAN.
    x_minFLOAT0.00Lowest X output value for the XY Pad.
    x_maxFLOAT1.00Highest X output value for the XY Pad.
    x_stepFLOAT0.010Snap size for X output. Use 0 to disable X snapping.
    x_defaultFLOAT0.50Default X value used as the intended reset/start value.
    y_minFLOAT0.00Lowest Y output value for the XY Pad.
    y_maxFLOAT1.00Highest Y output value for the XY Pad.
    y_stepFLOAT0.010Snap size for Y output. Use 0 to disable Y snapping.
    y_defaultFLOAT0.50Default Y value used as the intended reset/start value.
    crosshair_visibleBOOLEANtrueShow guide lines through the current XY point.
    grid_visibleBOOLEANtrueShow a subtle grid behind the XY Pad for easier positioning.
    _normalizedFLOAT0.50000–1Internal: current normalized value (analog controls)
    _stateBOOLEANfalseInternal: current state
    _x_normalizedFLOAT0.50000–1Internal: current normalized X
    _y_normalizedFLOAT0.50000–1Internal: current normalized Y

    Outputs (5)

    NameTypeDescription
    FLOATFLOATCurrent value (analog controls)
    INTINTFLOAT output truncated toward zero
    BOOLEANBOOLEANCurrent state (toggle / button)
    XFLOATCurrent X coordinate
    YFLOATCurrent Y coordinate