13 KiB
| name | description |
|---|---|
| comfyui-react-widget | Create React widgets in ComfyUI custom nodes. Covers createReactWidget wrapping, two-way data binding, render synchronization, extension registration, and component authoring conventions. Use when building new React widgets, debugging rendering issues, or registering custom widget types. |
ComfyUI React Widget
This project uses the createReactWidget factory function to mount React components as ComfyUI DOM widgets. This document describes how the entire mechanism works, key considerations, and complete examples.
Architecture Overview
ComfyUI (LGraphNode)
└── addDOMWidget(name, type, container, options)
└── container (HTMLDivElement)
└── React Root (createRoot)
└── <YourWidget value={...} onChange={...} />
- currentValue — Always stored as a JSON string for ComfyUI serialization/deserialization
- render() — Called on every value change, passing the latest props to the React Root
- getValue / setValue — ComfyUI calls these hooks to sync node values
- serializeValue — Called when ComfyUI builds the API payload, returns currentValue
Core Files
| File | Responsibility |
|---|---|
src/lib/create-react-widget.ts |
Widget factory, manages React Root, value storage, and ComfyUI two-way binding |
src/index.ts |
ComfyUI extension entry point, registers getCustomWidgets |
src/components/widgets/ |
React widget components |
Creating a New Widget: Complete Flow
1. Write the React Component
// src/components/widgets/MyWidget.tsx
import type { ReactWidgetProps } from '@/lib/create-react-widget'
export interface MyData {
text: string
count: number
}
export function MyWidget({ value, onChange }: ReactWidgetProps<MyData>) {
// Key: derive data from value prop, don't use useState for main data
const data: MyData = value && typeof value === 'object'
? value as MyData
: { text: '', count: 0 }
function update(patch: Partial<MyData>) {
onChange({ ...data, ...patch })
}
return (
<div>
<Input value={data.text} onChange={e => update({ text: e.target.value })} />
</div>
)
}
2. Export the Component
// src/components/widgets/index.ts
export { MyWidget } from './MyWidget'
export type { MyData } from './MyWidget'
3. Register Widget Type in Entry Point
// src/index.ts
const [{ createReactWidget }, { MyWidget }] = await Promise.all([
import('@/lib/create-react-widget'),
import('@/components/widgets'),
])
globalThis.comfyAPI!.app.app.registerExtension({
name: 'EasyMedia.widgets',
async setup() {
addStylesheet(`/${import.meta.env.PROJECT_NAME}/globals.css`)
},
getCustomWidgets() {
return {
MY_WIDGET: createReactWidget<MyData>(MyWidget, {
defaultValue: JSON.stringify({ text: '', count: 0 }),
domWidgetOptions: {
getMinHeight: () => 80,
},
}),
}
},
})
4. Declare Corresponding Input Type in Python Node
# nodes.py — Input type name must match getCustomWidgets key
@classmethod
def INPUT_TYPES(cls):
return {
"required": {
"my_data": ("MY_WIDGET", {}),
}
}
createReactWidget Parameters
createReactWidget<T>(Component, options?)
| Parameter | Type | Description |
|---|---|---|
Component |
React.ComponentType<ReactWidgetProps<T>> |
The React component to render |
options.defaultValue |
string |
Initial JSON string, defaults to '' |
options.height |
number |
Fixed container height (px), auto-sized if not set |
options.domWidgetOptions |
DOMWidgetOptions |
Passed through to addDOMWidget, can override getMinHeight, getMaxHeight, hideOnZoom, etc. |
ReactWidgetProps<T>
interface ReactWidgetProps<T extends object | string = object> {
value: T // Current deserialized value
onChange: (value: T) => void // Update value and trigger re-render
inputName: string // Node input name
node: any // LGraphNode instance
widget: DOMWidget // DOMWidget instance for this widget
app: ComfyApp // ComfyApp instance
}
Receiving widget and node Information
import type { ReactWidgetProps } from '@/lib/create-react-widget'
import type { DOMWidget } from '@comfyorg/comfyui-frontend-types'
export function MyWidget({ value, onChange, inputName, node, app, widget }: ReactWidgetProps) {
// node properties
const nodeId = node.id // Node unique ID
const nodeName = node.name // Node type name
const nodeType = node.type // Node class type
// widget properties
const widgetValue = widget.options?.serialize // widget serialization options
// app access
// app.ui, app.graph, app.commandMenu, etc.
return <div>...</div>
}
Two-Way Data Binding Mechanism
Internal Update (User Interacts with Component)
User interaction → onChange(newValue)
→ currentValue = JSON.stringify(newValue) // Persist
→ setDirtyCanvas(true, true) // Notify ComfyUI canvas to refresh
→ render() // Must call! Pass new props
External Update (ComfyUI Loads Workflow/Undo/Redo)
ComfyUI calls setValue(jsonString)
→ currentValue = jsonString
→ render() // Re-render with new value
Serialization (Building API Payload)
ComfyUI calls serializeValue()
→ Returns currentValue (JSON string)
Key Considerations
1. Must Call render() After onChange
This is the most common bug. After onChange callback updates currentValue, you must call render() to pass the new value to the component. Otherwise the React component won't re-render (no state change triggers the update).
// Wrong: missing render(), component doesn't update
onChange: (v: T) => {
currentValue = JSON.stringify(v)
comfyNode.setDirtyCanvas(true, true)
}
// Correct
onChange: (v: T) => {
currentValue = JSON.stringify(v)
comfyNode.setDirtyCanvas(true, true)
render()
}
2. Derive Main Data from value Prop, Don't Use useState
The main data (i.e., data to be serialized to ComfyUI) must be read from the value prop, not stored in React state. Reason: ComfyUI may externally update values via setValue (loading workflows, undo, etc.), and React must render with new props.
// Wrong: storing main data in state, external setValue won't sync
const [items, setItems] = useState(value)
// Correct: derive directly from value
const items = Array.isArray(value) ? value : []
useState is only for UI temporary state (e.g., draft values in input fields) that doesn't affect serialized data.
3. Defensive Parsing of value
When defaultValue is an empty string, parseValue returns the empty string instead of an empty array/object, so defensive handling is needed in components:
const items: MyItem[] = Array.isArray(value) ? value : []
const data: MyData = value && typeof value === 'object' ? value as MyData : { text: '' }
4. Use Top-Level await + Dynamic Import in Entry Point
src/index.ts uses await Promise.all([...dynamic imports...]) to load modules, ensuring React and widget code are code-split by Bun into separate chunks to avoid bloating the ComfyUI main JS bundle.
// Dynamic import, triggers Bun code splitting
const [{ createReactWidget }, { MyWidget }] = await Promise.all([
import('@/lib/create-react-widget'),
import('@/components/widgets'),
])
5. getCustomWidgets Key Must Match Python Type Name
The type string in Python INPUT_TYPES (e.g., "MY_WIDGET") must exactly match the key in the object returned by getCustomWidgets().
Complete Example Reference
React Component (src/components/widgets/ColorPaletteWidget.tsx)
import { useState } from 'react'
import { Button } from '@/components/ui/button'
import { Input } from '@/components/ui/input'
import { uuid } from '@/lib/uuid'
import type { ReactWidgetProps } from '@/lib/create-react-widget'
export interface ColorPreset {
id: string
name: string
hexColor: string
}
export function ColorPaletteWidget({ value, onChange }: ReactWidgetProps<ColorPreset[]>) {
// Main data derived from value
const presets: ColorPreset[] = Array.isArray(value) ? value : []
// UI temporary state can use useState
const [newName, setNewName] = useState('')
function addPreset() {
if (!newName.trim()) return
onChange([...presets, {
id: uuid(),
name: newName.trim(),
hexColor: '#000000',
}])
setNewName('')
}
function removePreset(id: string) {
onChange(presets.filter(preset => preset.id !== id))
}
function updatePreset(id: string, patch: Partial<ColorPreset>) {
onChange(presets.map(preset => preset.id === id ? { ...preset, ...patch } : preset))
}
return (
<div className="flex flex-col gap-2 p-2 text-sm">
{/* ... JSX ... */}
</div>
)
}
Entry Registration (src/index.ts)
const [{ createReactWidget }, { ColorPaletteWidget }] = await Promise.all([
import('@/lib/create-react-widget'),
import('@/components/widgets'),
])
globalThis.comfyAPI!.app.app.registerExtension({
name: 'EasyMedia.widgets',
async setup() {
addStylesheet(`/${import.meta.env.PROJECT_NAME}/globals.css`)
},
getCustomWidgets() {
return {
COLOR_PALETTE: createReactWidget<ColorPreset[]>(ColorPaletteWidget, {
defaultValue: JSON.stringify([]),
domWidgetOptions: { getMinHeight: () => 100 },
}),
}
},
})
Debugging Checklist
| Symptom | Cause | Solution |
|---|---|---|
| Component doesn't update after user action | onChange missing render() |
Add render() at end of onChange |
| Shows old data after loading workflow | Main data stored in useState |
Derive from value prop instead |
| Node value always empty | defaultValue not set or type name mismatch |
Check createReactWidget defaultValue and Python type name |
| Widget height is 0 | getMinHeight not set |
Set getMinHeight in domWidgetOptions |
| Styles not applying | CSS not loaded | Confirm addStylesheet is called in setup() |
Localization (i18n)
All static text in widget components (labels, titles, placeholders, tooltips, context-menu items, aria-labels) must use the localization system instead of hardcoded strings.
How It Works
The current ComfyUI locale is read from app?.ui?.settings?.settingsValues?.['Comfy.Locale'] in the top-level widget component and provided via LocaleContext. Child components consume it with useT().
Message catalogs live in frontend/messages/:
frontend/messages/
en.json ← English (fallback)
zh.json ← Chinese
Keys are organized by section (one section per component). Parameterized strings use {name} placeholders.
1. Add Keys to Both Catalogs
// messages/en.json
{
"myWidget": {
"addItem": "Add item",
"deleteItem": "Delete item",
"itemLabel": "Item {n}",
"placeholder": "Enter text…"
}
}
// messages/zh.json
{
"myWidget": {
"addItem": "添加项目",
"deleteItem": "删除项目",
"itemLabel": "项目 {n}",
"placeholder": "请输入文字…"
}
}
2. Provide Locale in the Top-Level Widget Component
Only the root *Widget.tsx component does this. Pass the raw locale string to LocaleContext.Provider:
// src/components/widgets/MyWidget.tsx
import { LocaleContext } from '@/lib/i18n'
export function MyWidget({ value, onChange, app }: ReactWidgetProps<MyData>) {
const locale = app?.ui?.settings?.settingsValues?.['Comfy.Locale']
return (
<LocaleContext.Provider value={locale}>
{/* child components */}
</LocaleContext.Provider>
)
}
3. Consume in Any Child Component
// src/components/widgets/timeline/MyTrack.tsx
import { useT } from '@/lib/i18n'
export function MyTrack() {
const t = useT()
return (
<div>
{/* Simple key */}
<Button>{t('myWidget.addItem')}</Button>
{/* With parameter */}
<span>{t('myWidget.itemLabel', { n: 3 })}</span>
{/* en → "Item 3" zh → "项目 3" */}
{/* Placeholder */}
<Textarea placeholder={t('myWidget.placeholder')} />
{/* Aria-label */}
<button aria-label={t('myWidget.deleteItem')} />
</div>
)
}
4. Common Shared Keys
Keys in the "common" section are shared across all components:
| Key | en | zh |
|---|---|---|
common.cancel |
Cancel | 取消 |
common.save |
Save | 保存 |
common.add |
Add | 添加 |
common.delete |
Delete | 删除 |
const t = useT()
<Button>{t('common.cancel')}</Button>
Rule
Every widget component that renders static text must call
useT()and reference a message key.
Hardcoded strings in JSX or props are not allowed.