@kuttl/react

React adapter for Kuttl — AI-powered, non-destructive UI patching. Let your users describe UI changes in plain English ("make the title larger", "remove the sidebar"); Kuttl turns them into structured patches applied to the live DOM without touching your component code. Changes can be previewed, persisted, exported, and undone.

The AI runs through a hosted backend proxy that owns the LLM credentials, so no API keys are ever exposed in the browser.

Install

npm install @kuttl/react

Requires React 18 or 19 as a peer dependency.

Usage

Wrap your app in KuttlProvider and render KuttlPanel anywhere inside it. Mark the elements you want to be editable with a data-uid attribute.

import { KuttlProvider, KuttlPanel } from '@kuttl/react'

export default function App() {
  return (
    <KuttlProvider persistKey="my-app">
      <div data-uid="page">{/* your app */}</div>
      <KuttlPanel />
    </KuttlProvider>
  )
}

Provider props

<KuttlProvider
  persistKey="my-app"                     // localStorage key for patch persistence
  uidAttribute="data-uid"                 // attribute used as element identity
  descriptionAttribute="data-description" // attribute used as an element label for AI context
  onSelect={(el) => console.log(el)}      // callback when an element is selected
  debug                                   // log AI prompt details to console
>

Context API (useKuttlContext)

| Method | Description | |---|---| | patch(patches) | Apply one or more patches | | unpatch(id) | Remove a patch by id | | undo() | Remove the most recently applied patch | | reset() | Remove all patches and clear selection | | exportPatches() | Serialize current patches to a JSON string | | importPatches(json) | Hydrate the store from exported JSON | | prompt(text) | Send a natural-language instruction to the AI | | preview(patches) | Dry-run: compute the result without committing | | generateSemanticPatches(op, uid) | Generate compound, layout-safe patches for an operation | | selectedElement | Currently selected element (uid, tag, description, …) | | isSelectActive | Whether click-to-select mode is active | | toggleSelect() | Enter/exit click-to-select mode | | clearSelection() | Deselect the current element |

Hooks

// Read overrides for a specific element (opt-in structural patching)
const { style, hidden, reorder } = useKuttl("nav-actions");

// Send AI prompts and track loading/error state
const { sendPrompt, status, isLoading } = useKuttlAI();

useKuttl(uid).reorder(children) re-orders a React children array according to any active reorder patch on that uid — useful in components that manage their own children dynamically.

Supported operations

restyle, hide, show, reorder, addClass, removeClass, setText, and move. Style-based operations survive React re-renders; DOM operations are re-applied automatically when the tree changes.

License

MIT © Samuel Isirima