Handlebars Editor

Installation

pnpm dlx @docyrus/cli add @docyrus/ui-handlebars-editor

pnpm add handlebars @uiw/react-codemirror @uiw/codemirror-extensions-langs @codemirror/autocomplete @codemirror/language @codemirror/lint @codemirror/state @codemirror/view @lezer/highlight

npx shadcn@latest add button dropdown-menu tooltip textarea

Overview

HandlebarsEditor is a self-contained workbench for the Handlebars templating language. It has two tab-panel panes, each using the variant="line" style:

Rendering happens automatically as you type (debounced). Flip between TEMPLATE and DATA from the left-pane tabs; flip between OUTPUT and PREVIEW from the right-pane tabs.

Features

• Live rendering — debounced re-render on every input or template change.
• IntelliSense — autocomplete with snippet expansion for Handlebars built-in block helpers (#if, #each, #with, #unless), inline helpers (lookup, log), and common comparison / math / formatting helpers.
• Context path completion — paths extracted from the JSON input (e.g. user.name, orders.[0].total) are surfaced in autocomplete as you type.
• Hover documentation — signatures, parameter docs and examples on hover.
• Inline linting — parse errors and unmatched block tags are underlined.
• OUTPUT / PREVIEW tabs — read the rendered string in CodeMirror, or flip to the PREVIEW tab to see it rendered inside a sandboxed iframe.
• Custom helpers and partials — pass helpers and partials to register your own at render time. Registrations are scoped to a private Handlebars instance so the global one is never mutated.
• Samples menu — load ready-made input + template pairs.
• AI Assistant drawer — opt-in chat panel built on ai-elements that slides in from the left and wires to your own LLM via onSendMessage.
• Controlled or uncontrolled — drive template / input yourself or let the component own them.
• Flexible layout — horizontal or vertical, with the input and output panes individually toggleable.
• Theme-aware — follows the Docyrus light / dark theme.

Usage

import { HandlebarsEditor } from "@docyrus/ui/components/handlebars-editor";

export function Example() {
  return (
    <HandlebarsEditor
      defaultTemplate="<p>Hello, {{firstName}} {{lastName}}!</p>"
      defaultInput={{ firstName: "Fred", lastName: "Smith" }}
      onResult={(html) => console.log(html)}
    />
  );
}

Controlled

Drive both panes from your own state:

const [template, setTemplate] = useState("");
const [input, setInput] = useState("{}");

<HandlebarsEditor
  template={template}
  onTemplateChange={setTemplate}
  input={input}
  onInputChange={setInput}
/>

Custom helpers

Register additional helpers — they'll be available inside the template and surfaced in the autocomplete dropdown:

<HandlebarsEditor
  defaultTemplate="{{formatCurrency total 'USD'}}"
  defaultInput={{ total: 1250 }}
  helpers={{
    formatCurrency: (value, currency) =>
      new Intl.NumberFormat("en-US", {
        style: "currency",
        currency: String(currency ?? "USD")
      }).format(Number(value))
  }}
/>

Memoize the helpers / partials objects if they're dynamic — the editor reads them on each render but does not re-render when only those references change.

Custom partials

Partials let you split a template into reusable fragments:

<HandlebarsEditor
  defaultTemplate="{{> greeting }}, welcome back."
  defaultInput={{ name: "Ada" }}
  partials={{
    greeting: "Hello, {{name}}"
  }}
/>

Output rendering

The OUTPUT tab highlights the rendered result according to outputMode: HTML syntax highlighting (outputMode="html", the default), Markdown syntax highlighting (outputMode="markdown"), or plain text (outputMode="text"). The PREVIEW tab renders the same string as formatted content — an HTML iframe for html / text, and formatted Markdown (via the shared react-markdown renderer) for markdown:

<HandlebarsEditor
  defaultTemplate="<button style='color:white;background:#2563eb;padding:6px 12px;border-radius:4px;border:0'>{{label}}</button>"
  defaultInput={{ label: "Click me" }}
  outputMode="html"
/>

Markdown output

Set outputMode="markdown" for templates that render Markdown. The OUTPUT tab highlights the Markdown source and the PREVIEW tab shows it as formatted content (headings, lists, tables, blockquotes) using the same renderer that powers comments and chat — no extra dependency:

<HandlebarsEditor
  defaultTemplate={"# {{title}}\n\n**Owner:** {{owner}}\n\n{{#each tasks}}- {{name}}\n{{/each}}"}
  defaultInput={{ title: "Sprint 12", owner: "Ada", tasks: [{ name: "Ship editor" }] }}
  outputMode="markdown"
/>

AI Assistant

Pass an aiAssistant config to add an AI Assistant button to the toolbar. Clicking it slides a chat drawer in from the left of the editor, built on ai-elements (Conversation, Message). Wire onSendMessage to your LLM and return the reply (sync or async):

<HandlebarsEditor
  defaultTemplate="<p>Hello, {{name}}</p>"
  aiAssistant={{
    onSendMessage: async (message, { template, input, history }) => {
      const response = await fetch("/api/chat", {
        method: "POST",
        body: JSON.stringify({ message, template, input, history })
      });
      const { reply } = await response.json();
      return reply;
    },
    suggestions: [
      "Explain this template",
      "Show me an #each example",
      "How do I conditionally render?"
    ]
  }}
/>

Pass aiAssistant={true} to mount the chat shell without a backend (useful while wiring one — messages are stored locally but no reply arrives).

Standalone template editor

HandlebarsCodeEditor is the template pane on its own — drop it into a form or an automation node config when you only need to capture a Handlebars template.

import { HandlebarsCodeEditor } from "@docyrus/ui/components/handlebars-editor";

const [value, setValue] = useState("");

<HandlebarsCodeEditor
  value={value}
  onChange={setValue}
  placeholder="Hello, {{name}}"
  contextPaths={["name", "email", "company.title"]}
/>

contextPaths and helperNames feed the autocomplete with project-specific suggestions in addition to the built-ins.

Headless rendering

useHandlebars debounces and renders a template against an already-parsed context value, with no UI:

import { useHandlebars } from "@docyrus/ui/components/handlebars-editor";

function useGreeting(user: unknown) {
  const state = useHandlebars("Hello, {{name}}", user);

  return state.status === "success" ? state.result : "";
}

For a one-off render outside React, use renderHandlebars:

import { renderHandlebars } from "@docyrus/ui/components/handlebars-editor";

const state = renderHandlebars(
  "{{count}} items",
  { count: 3 }
);
// → { status: "success", result: "3 items" }

EditorAgent integration

Pair useApplyHandlebars with renderAiAssistant to give an LLM a writable template pane. The hook owns the editor's controlled state and ships an applyHandlebars tool that the agent calls to commit a new template — the tool also renders against the current input JSON and returns the rendered output preview so the agent can self-correct.

import { EditorAgent } from '@docyrus/ui/components/editor-agent';
import { HandlebarsEditor, useApplyHandlebars } from '@docyrus/ui/components/handlebars-editor';

export function HandlebarsPlayground({ client, user, agentId }) {
  const handlebars = useApplyHandlebars();
  const [aiOpen, setAiOpen] = useState(false);

  return (
    <HandlebarsEditor
      template={handlebars.template}
      onTemplateChange={handlebars.setTemplate}
      input={handlebars.input}
      onInputChange={handlebars.setInput}
      aiAssistantOpen={aiOpen}
      onAiAssistantOpenChange={setAiOpen}
      renderAiAssistant={({ open, onClose }) => (
        <EditorAgent
          agentId={agentId}
          client={client}
          user={user}
          open={open}
          onClose={onClose}
          clientTools={handlebars.tools}
        />
      )}
    />
  );
}

The matching backend agent must register a tool named applyHandlebars whose input schema mirrors { template: string (required), input?: any, explanation?: string }.

API Reference

HandlebarsEditor

HandlebarsCodeEditor

useHandlebars

useHandlebars(template: string, context: unknown, options?: UseHandlebarsOptions): HandlebarsEvaluationState

Components

Type Exports

Helpers