--- name: comfyui-react-widget description: 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) └── ``` - **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 ```tsx // 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) { // 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) { onChange({ ...data, ...patch }) } return (
update({ text: e.target.value })} />
) } ``` ### 2. Export the Component ```ts // src/components/widgets/index.ts export { MyWidget } from './MyWidget' export type { MyData } from './MyWidget' ``` ### 3. Register Widget Type in Entry Point ```ts // 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(MyWidget, { defaultValue: JSON.stringify({ text: '', count: 0 }), domWidgetOptions: { getMinHeight: () => 80, }, }), } }, }) ``` ### 4. Declare Corresponding Input Type in Python Node ```python # nodes.py — Input type name must match getCustomWidgets key @classmethod def INPUT_TYPES(cls): return { "required": { "my_data": ("MY_WIDGET", {}), } } ``` --- ## createReactWidget Parameters ```ts createReactWidget(Component, options?) ``` | Parameter | Type | Description | |-----------|------|-------------| | `Component` | `React.ComponentType>` | 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\ ```ts interface ReactWidgetProps { 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 ```tsx 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
...
} ``` --- ## 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). ```ts // 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. ```tsx // 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: ```tsx 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. ```ts // 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`) ```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) { // 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) { onChange(presets.map(preset => preset.id === id ? { ...preset, ...patch } : preset)) } return (
{/* ... JSX ... */}
) } ``` ### Entry Registration (`src/index.ts`) ```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(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 ```jsonc // 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`: ```tsx // src/components/widgets/MyWidget.tsx import { LocaleContext } from '@/lib/i18n' export function MyWidget({ value, onChange, app }: ReactWidgetProps) { const locale = app?.ui?.settings?.settingsValues?.['Comfy.Locale'] return ( {/* child components */} ) } ``` ### 3. Consume in Any Child Component ```tsx // src/components/widgets/timeline/MyTrack.tsx import { useT } from '@/lib/i18n' export function MyTrack() { const t = useT() return (
{/* Simple key */} {/* With parameter */} {t('myWidget.itemLabel', { n: 3 })} {/* en → "Item 3" zh → "项目 3" */} {/* Placeholder */}