add_components: Insert HTML onto Canvas

Insert raw HTML — including Tailwind classes — directly onto the DesignJS canvas and receive the new component IDs for immediate follow-up operations.

The add_components tool is your agent’s primary way to place new content onto the canvas. You provide a raw HTML string and DesignJS parses it, creates the corresponding GrapesJS components, renders them in the canvas iframe, and returns the IDs of the newly created top-level components. Tailwind utility classes in your HTML are resolved correctly by the Tailwind v4 CDN loaded in the iframe — no build step required.

By default, new components are appended to the canvas root. Provide a target component ID to insert them as children of a specific existing component — useful for adding items to a list, inserting a row into a grid, or nesting elements inside a container.

Parameters

html · string · required

The raw HTML string to insert onto the canvas. Tailwind class names are supported and resolved correctly. You can insert a single element or a full section with nested children.

target · string

The ID of an existing component to use as the parent for the inserted HTML. If omitted, the HTML is appended to the canvas root. Obtain component IDs from get_tree or get_selection.

Response

componentIds · string[] · required

The IDs of the newly created top-level components. If your HTML string contains multiple sibling root elements, each gets its own ID in this array. Use these IDs immediately to call update_styles, get_html, or delete_nodes on the new components.

Example

request — append to canvas root

{
  "method": "tools/call",
  "params": {
    "name": "add_components",
    "arguments": {
      "html": "<section class=\"flex flex-col items-center py-20 bg-indigo-50\"><h2 class=\"text-3xl font-bold text-indigo-900\">Features</h2><p class=\"mt-4 text-indigo-700 max-w-lg text-center\">Everything your agent needs to design with confidence.</p></section>"
    }
  }
}

response

{
  "content": [
    {
      "type": "text",
      "text": "{\"componentIds\": [\"comp-new-001\"]}"
    }
  ]
}

The returned IDs are for the top-level elements in your HTML string. If you insert <section>...</section> containing nested <div> and <p> elements, only the <section>’s ID is returned. Use get_tree to explore the full subtree of the new component.

Inserting invalid HTML may result in unexpected GrapesJS component structures. Always provide well-formed HTML with properly closed tags.

After inserting components, call get_screenshot to visually confirm the layout before making additional changes. This is especially useful when inserting complex HTML with many nested elements.