Dragble Integration

Dragble Editor Integration

Overview

Dragble is an embeddable drag-and-drop email/web/popup editor. You integrate it into your application using either a framework wrapper (React, Vue, Angular) or the vanilla JavaScript SDK loaded from CDN.

Packages

The SDK itself (@dragble/editor-sdk) is CDN-only. It is loaded automatically by the framework wrappers from https://sdk.dragble.com/{version}/dragble-sdk.min.js. There is NO npm package for the SDK. NEVER suggest npm install @dragble/editor-sdk.

Key Concepts

• editorKey (required): Authentication key for your project. Format: ek_* or px_*.
• containerId: Auto-generated by wrappers. Required when using vanilla JS.
• Editor modes: "email" (default), "web", "popup".
• Design modes: "edit" (admin -- shows Row Actions for setting permissions), "live" (end-user -- enforces permissions). Default: "live".
• All async methods return Promises. There are no callback-based async APIs.

React

Installation

npm install dragble-react-editor

Types are included automatically via re-export from dragble-types.

Complete Example

import { useRef, useState } from "react";
import { DragbleEditor, type DragbleEditorRef, type DesignJson } from "dragble-react-editor";

export default function EmailEditor() {
  const editorRef = useRef<DragbleEditorRef>(null);
  const [lastSaved, setLastSaved] = useState<string | null>(null);

  const handleReady = (editor) => {
    console.log("Editor ready");
  };

  const handleSave = async () => {
    const editor = editorRef.current?.editor;
    if (!editor) return;

    // Export HTML
    const html = await editor.exportHtml();
    console.log("HTML:", html);

    // Export JSON (for saving/restoring designs)
    const json = await editor.exportJson();
    console.log("JSON:", json);
    setLastSaved(new Date().toISOString());
  };

  const handleLoad = () => {
    const editor = editorRef.current?.editor;
    if (!editor) return;

    // Load a previously saved design
    const savedDesign: DesignJson = JSON.parse(localStorage.getItem("design")!);
    editor.loadDesign(savedDesign);
  };

  return (
    <div>
      <div style={{ display: "flex", gap: 8, marginBottom: 8 }}>
        <button
        <button Saved</button>
      </div>
      <DragbleEditor
        ref={editorRef}
        editorKey="ek_your_editor_key"
        editorMode="email"
        height="800px"
       
        => console.log("Design changed:", data.type)}
        => console.error("Editor error:", err)}
      />
    </div>
  );
}

Props

Ref API (DragbleEditorRef)

const editorRef = useRef<DragbleEditorRef>(null);

// Access the SDK instance
const editor = editorRef.current?.editor;

// Check if the editor is ready
const ready = editorRef.current?.isReady();

The editor property exposes the full DragbleSDK interface. All methods are available after isReady() returns true.

Hook: useDragbleEditor

import { useDragbleEditor } from "dragble-react-editor";

function MyComponent() {
  const { ref, editor, isReady } = useDragbleEditor();

  return (
    <DragbleEditor ref={ref} editorKey="ek_..." />
  );
}

Vue 3

Installation

npm install dragble-vue-editor

Types are included automatically via re-export from dragble-types.

Complete Example

<template>
  <div>
    <div style="display: flex; gap: 8px; margin-bottom: 8px">
      <button @click="handleSave">Save</button>
      <button @click="handleLoadBlank">Load Blank</button>
    </div>
    <DragbleEditor
      ref="editorRef"
      editor-key="ek_your_editor_key"
      editor-mode="email"
      height="800px"
      @ready="onReady"
      @change="onChange"
      @error="onError"
    />
  </div>
</template>

<script setup lang="ts">
import { ref } from "vue";
import { DragbleEditor, type DragbleSDK, type DesignJson } from "dragble-vue-editor";

const editorRef = ref<InstanceType<typeof DragbleEditor>>();

const DragbleSDK) => {
  console.log("Editor ready");
};

const { design: DesignJson; type: string }) => {
  console.log("Changed:", data.type);
};

const Error) => {
  console.error("Editor error:", error);
};

const handleSave = async () => {
  const html = await editorRef.value?.exportHtml();
  const json = await editorRef.value?.exportJson();
  console.log("Exported:", { html, json });
};

const handleLoadBlank = () => {
  editorRef.value?.loadBlank();
};
</script>

Props

Vue props use kebab-case in templates. All the same configuration options as React apply:

Vue also exposes many props as top-level (e.g., merge-tags, appearance, tools, fonts) in addition to the options prop. Top-level props are merged into options internally. Either approach works; do not set the same option in both places.

Emits

Reactive Watchers

The Vue component automatically watches for changes to these props and updates the editor at runtime without re-initialization:

• design -- calls loadDesign() when changed
• merge-tags -- calls setMergeTags() when changed
• modules -- calls setModules() when changed
• display-conditions -- calls setDisplayConditions() when changed

Component Ref Methods

All SDK methods are exposed via expose() on the component ref:

<script setup lang="ts">
const editorRef = ref<InstanceType<typeof DragbleEditor>>();

// After ready:
await editorRef.value?.exportHtml();
await editorRef.value?.exportJson();
await editorRef.value?.exportImage();
await editorRef.value?.exportPdf();
editorRef.value?.loadDesign(design);
editorRef.value?.loadBlank();
editorRef.value?.undo();
editorRef.value?.redo();
editorRef.value?.showPreview("desktop");
editorRef.value?.setMergeTags({ customMergeTags: [...] });
editorRef.value?.setModules([...]);
editorRef.value?.addEventListener("row:selected", (data) => { ... });
// ... all DragbleSDK methods are available
</script>

Composable: useDragbleEditor

For direct SDK access without the component:

<script setup lang="ts">
import { useDragbleEditor } from "dragble-vue-editor";

const { editor, isReady, containerId } = useDragbleEditor({
  editorKey: "ek_your_editor_key",
  editorMode: "email",
});

const handleExport = async () => {
  if (isReady.value && editor.value) {
    const html = await editor.value.exportHtml();
    console.log(html);
  }
};
</script>

<template>
  <div :id="containerId" style="height: 600px" />
  <button @click="handleExport" :disabled="!isReady">Export</button>
</template>

Angular

Installation

npm install dragble-angular-editor

Types are included automatically via re-export from dragble-types.

Complete Example (Standalone Component)

import { Component, ViewChild } from "@angular/core";
import { DragbleEditorComponent } from "dragble-angular-editor";

@Component({
  selector: "app-email-editor",
  standalone: true,
  imports: [DragbleEditorComponent],
  template: `
    <div>
      <div style="display: flex; gap: 8px; margin-bottom: 8px">
        <button (click)="handleSave()">Save</button>
        <button (click)="handleLoadBlank()">Load Blank</button>
      </div>
      <dragble-editor
        #editor
        editorKey="ek_your_editor_key"
        editorMode="email"
        height="800px"
        (ready)="onReady($event)"
        (change)="onChange($event)"
        (error)="onError($event)"
      ></dragble-editor>
    </div>
  `,
})
export class EmailEditorComponent {
  @ViewChild("editor") editor!: DragbleEditorComponent;

  onReady(sdk: any) {
    console.log("Editor ready");
  }

  onChange(data: { design: any; type: string }) {
    console.log("Changed:", data.type);
  }

  onError(error: Error) {
    console.error("Editor error:", error);
  }

  async handleSave() {
    const html = await this.editor.exportHtml();
    const json = await this.editor.exportJson();
    console.log("Exported:", { html, json });
  }

  handleLoadBlank() {
    this.editor.loadBlank();
  }
}

NgModule Pattern (Legacy)

For Angular apps not using standalone components:

import { NgModule } from "@angular/core";
import { DragbleEditorModule } from "dragble-angular-editor";

@NgModule({
  imports: [DragbleEditorModule],
})
export class AppModule {}

Then use <dragble-editor> in your templates the same way.

Inputs

Outputs

Change Detection

The Angular component implements OnChanges. When these inputs change after initialization, the editor updates automatically:

• design -- calls loadDesign()
• mergeTags -- calls setMergeTags()
• modules -- calls setModules()
• displayConditions -- calls setDisplayConditions()

Public Methods

All SDK methods are exposed as public methods on the component:

@ViewChild("editor") editor!: DragbleEditorComponent;

// Design
this.editor.loadDesign(design);
this.editor.loadBlank();
this.editor.saveDesign((design) => { ... });
await this.editor.getDesign();

// Export
await this.editor.exportHtml();
await this.editor.exportJson();
await this.editor.exportPlainText();
await this.editor.exportImage();
await this.editor.exportPdf();
await this.editor.exportZip();

// Configuration
this.editor.setMergeTags(config);
this.editor.setModules(modules);
this.editor.setFonts(config);
this.editor.setBodyValues(values);
this.editor.setAppearance(config);
this.editor.setLocale("fr-FR");
this.editor.setTextDirection("rtl");

// Actions
this.editor.undo();
this.editor.redo();
this.editor.save();
this.editor.showPreview("desktop");
this.editor.hidePreview();

// Raw SDK instance
const sdk = this.editor.getEditor();

// Events
const unsub = this.editor.addEventListener("row:selected", (data) => { ... });
unsub(); // unsubscribe

Vanilla JavaScript

The SDK is loaded from CDN. There is no npm package.

Basic Example

<!DOCTYPE html>
<html>
<head>
  <title>Dragble Editor</title>
  <script src="https://sdk.dragble.com/latest/dragble-sdk.min.js"></script>
</head>
<body>
  <div id="editor-container" style="height: 800px;"></div>

  <script>
    // Global singleton
    dragble.init({
      containerId: "editor-container",
      editorKey: "ek_your_editor_key",
      editorMode: "email",
    });

    dragble.addEventListener("editor:ready", () => {
      console.log("Editor ready");
    });

    // Save
    document.getElementById("save-btn")?.addEventListener("click", async () => {
      const html = await dragble.exportHtml();
      const json = await dragble.exportJson();
      console.log("Exported:", { html, json });
    });
  </script>
</body>
</html>

Multiple Instances with createEditor()

The global dragble object is a singleton. For multiple editors on the same page, use createEditor():

<div id="editor-1" style="height: 600px;"></div>
<div id="editor-2" style="height: 600px;"></div>

<script src="https://sdk.dragble.com/latest/dragble-sdk.min.js"></script>
<script>
  const editor1 = createEditor({
    containerId: "editor-1",
    editorKey: "ek_key_1",
    editorMode: "email",
  });

  const editor2 = createEditor({
    containerId: "editor-2",
    editorKey: "ek_key_2",
    editorMode: "web",
  });

  editor1.addEventListener("editor:ready", () => {
    console.log("Editor 1 ready");
  });

  editor2.addEventListener("editor:ready", () => {
    console.log("Editor 2 ready");
  });
</script>

Important: Do NOT use dragble.init() for multiple instances. Each createEditor() call returns an independent SDK instance with its own lifecycle.

Loading a Saved Design

dragble.init({
  containerId: "editor-container",
  editorKey: "ek_your_editor_key",
  design: savedDesignJson, // Pass design JSON at init time
});

// Or load after init:
dragble.addEventListener("editor:ready", () => {
  dragble.loadDesign(savedDesignJson);
});

Cleanup

// Destroy the editor instance and clean up resources
dragble.destroy();

TypeScript Types

Framework Wrappers (React, Vue, Angular)

Types are automatically available. All wrappers re-export the full type surface from dragble-types:

import type {
  DragbleSDK,
  DragbleConfig,
  DragbleCallbacks,
  DesignJson,
  EditorOptions,
  EditorMode,
  MergeTag,
  MergeTagGroup,
  Module,
  PopupConfig,
  ExportHtmlOptions,
  ExportImageData,
  ExportPdfData,
  ExportZipData,
  CollaborationFeaturesConfig,
  UserInfo,
  CommentAction,
  // ... all types available
} from "dragble-react-editor"; // or "dragble-vue-editor" or "dragble-angular-editor"

Vanilla TypeScript

Install the types package as a dev dependency:

npm install --save-dev dragble-types

Then declare the global SDK:

import type { DragbleSDK } from "dragble-types";

declare global {
  const dragble: DragbleSDK;
  function createEditor(config: import("dragble-types").DragbleConfig): DragbleSDK;
}

// Now fully typed
dragble.init({
  containerId: "editor",
  editorKey: "ek_your_key",
});

const html: string = await dragble.exportHtml();

SDK & Editor Versioning

CDN URL Structure

https://sdk.dragble.com/{sdkVersion}/dragble-sdk.min.js

Version Channels

Wrapper Props

All framework wrappers accept four versioning props:

Precedence Rules

• sdkUrl overrides sdkVersion. If both are set, sdkVersion is ignored and a console warning is emitted.
• editorUrl overrides editorVersion. Same behavior.

Examples

// React: Pin SDK to v1.2.3, editor to stable
<DragbleEditor
  editorKey="ek_..."
  sdkVersion="v1.2.3"
  editorVersion="stable"
/>

// React: Use a self-hosted SDK
<DragbleEditor
  editorKey="ek_..."
  sdkUrl="https://cdn.example.com/dragble-sdk.min.js"
  editorUrl="https://editor.example.com"
/>

<!-- Vue -->
<DragbleEditor
  editor-key="ek_..."
  sdk-version="v1.2.3"
  editor-version="stable"
/>

<!-- Vanilla: specific version -->
<script src="https://sdk.dragble.com/v1.2.3/dragble-sdk.min.js"></script>

Events

Register event listeners with addEventListener. It returns an unsubscribe function.

const unsubscribe = editor.addEventListener("design:updated", (data) => {
  console.log("Design updated:", data);
});

// Later: stop listening
unsubscribe();

// Or use removeEventListener with the same callback reference
editor.removeEventListener("design:updated", callback);

All Events

Callbacks

Callbacks are passed via the callbacks prop (framework wrappers) or the callbacks key in the init config (vanilla JS). They are divided into non-blocking and blocking.

Non-Blocking Callbacks

These fire-and-forget. Return value is ignored.

Blocking Callbacks (Return a Promise)

The editor waits for the Promise to resolve before continuing.

Example: Callbacks in React

<DragbleEditor
  editorKey="ek_..."
  => console.log("Ready")}
  => console.log("Changed:", data.type)}
  callbacks={{
    linkClick: (data) => window.open(data.url, "_blank"),
    onModuleSave: async (data) => {
      // data includes: id?, name, category, mode, type, data (row JSON), html, thumbnail?
      const result = await fetch("/api/modules", {
        method: "POST",
        body: JSON.stringify(data),
      });
      const { id } = await result.json();
      return { success: true, moduleId: id };
    },
    onModuleDelete: async (data) => {
      const response = await fetch(`/api/modules/${data.id}`, {
        method: "DELETE",
      });
      return response.ok
        ? { success: true }
        : { success: false, error: "Failed to delete module" };
    },
    onPreview: async (html) => {
      // Replace merge tags with sample data before preview
      return html.replace(/\{\{first_name\}\}/g, "Jane");
    },
  }}
/>

Example: Callbacks in Vanilla JS

dragble.init({
  containerId: "editor-container",
  editorKey: "ek_your_editor_key",
  callbacks: {
    onReady: () => console.log("Ready"),
    onChange: (data) => console.log("Changed"),
    linkClick: (data) => window.open(data.url, "_blank"),
    onModuleSave: async (data) => {
      const res = await fetch("/api/modules", {
        method: "POST",
        body: JSON.stringify(data),
      });
      const { id } = await res.json();
      return { success: true, moduleId: id };
    },
    onModuleDelete: async (data) => {
      const response = await fetch(`/api/modules/${data.id}`, {
        method: "DELETE",
      });
      return response.ok
        ? { success: true }
        : { success: false, error: "Failed to delete module" };
    },
    onPreview: async (html) => {
      return html.replace(/\{\{first_name\}\}/g, "Jane");
    },
  },
});

Modules (Reusable Rows)

Modules let users save rows as reusable blocks that appear in the Modules Library accordion for drag-and-drop insertion.

Module Data Structure

interface Module {
  id: string;                          // Unique identifier
  name: string;                        // Display name in the library
  category: string;                    // Category (normalized to lowercase by SDK)
  mode: "email" | "web" | "popup";    // Editor mode
  type: "standard" | "synced";        // standard = editable copy, synced = linked to source
  thumbnail?: string;                  // Optional preview image URL
  data: object;                        // Saved row JSON
}

Module categories are canonicalized to lowercase by the SDK/editor. "Banner", "banner", and "BANNER" all become "banner". The UI displays them capitalized.

Methods

// Replace the entire modules list
editor.setModules([
  {
    id: "hero-banner",
    name: "Hero Banner",
    category: "Banner",    // normalized to "banner"
    mode: "email",
    type: "standard",
    thumbnail: "https://cdn.example.com/thumbs/hero.png",
    data: heroRowJson,
  },
]);

// Append a single module
editor.addModule({
  id: "footer-standard",
  name: "Standard Footer",
  category: "footer",
  mode: "email",
  type: "standard",
  data: footerRowJson,
});

// Remove a module by ID
editor.removeModule("hero-banner");

Synced Modules

Synced modules (type: "synced") stay linked to their source. When you update a synced module, all designs using it reflect the changes on next load. Users cannot edit the content of a synced module inline — they must update the source module.

editor.setModules([
  {
    id: "legal-footer",
    name: "Legal Footer",
    category: "footer",
    mode: "email",
    type: "synced",  // Changes propagate to all designs
    data: legalFooterRowJson,
  },
]);

Module Save Data (Returned by onModuleSave)

interface ModuleSaveData {
  id?: string;               // Existing module ID (if editing)
  name: string;              // User-provided name
  category: string;          // Normalized to lowercase
  mode: "email" | "web" | "popup";
  type: "standard" | "synced";
  data: object;              // Row JSON
  html: string;              // Rendered HTML
  thumbnail?: string;        // Auto-generated thumbnail URL
}

Module Delete Data (Received by onModuleDelete)

interface ModuleDeleteData {
  id: string;
  name?: string;
  category?: string;
  type?: "standard" | "synced";
  mode?: "email" | "web" | "popup";
}

Complete Callback Example

<DragbleEditor
  editorKey="ek_..."
  callbacks={{
    onModuleSave: async (data) => {
      // data contains row data, html, thumbnail, mode, type, category
      const result = await fetch("/api/modules", {
        method: "POST",
        body: JSON.stringify(data),
      });
      const { id } = await result.json();
      return { success: true, moduleId: id };
    },
    onModuleDelete: async (data) => {
      const response = await fetch(`/api/modules/${data.id}`, {
        method: "DELETE",
      });
      return response.ok
        ? { success: true }
        : { success: false, error: "Failed to delete module" };
    },
  }}
/>

Common Mistakes

1. Container too small or hidden

The editor renders inside an iframe. If the container has height: 0, display: none, or is inside a collapsed accordion, the editor will appear blank. Always ensure the container has a visible, non-zero height.

// WRONG: no height
<DragbleEditor editorKey="ek_..." />

// RIGHT: explicit height
<DragbleEditor editorKey="ek_..." height="800px" />

2. Calling methods before the editor is ready

SDK methods throw or silently fail if called before editor:ready. Always wait for the ready event.

// WRONG
dragble.init({ ... });
dragble.exportHtml(); // Editor not ready yet!

// RIGHT
dragble.addEventListener("editor:ready", async () => {
  const html = await dragble.exportHtml();
});

3. Only saving HTML (losing the design)

HTML export is for sending/rendering. To let users edit their design later, you must also save the design JSON.

// WRONG: only save HTML
const html = await editor.exportHtml();
saveToDB(html);

// RIGHT: save both
const html = await editor.exportHtml();
const json = await editor.exportJson();
saveToDB({ html, json });

// Later: restore
editor.loadDesign(savedJson);

4. Using dragble.init() for multiple editors

The global dragble is a singleton. Calling init() twice replaces the first editor. Use createEditor() for multiple instances.

// WRONG
dragble.init({ containerId: "editor-1", ... });
dragble.init({ containerId: "editor-2", ... }); // Replaces editor-1!

// RIGHT
const editor1 = createEditor({ containerId: "editor-1", ... });
const editor2 = createEditor({ containerId: "editor-2", ... });

Framework wrappers handle this automatically -- each <DragbleEditor> component creates its own instance via createEditor().

5. Using wrong init parameters

Dragble uses containerId + editorKey. Do NOT use id, projectId, or apiKey -- those are from other editors.

// WRONG (Unlayer-style)
dragble.init({ id: "editor", projectId: 12345 });

// RIGHT
dragble.init({ containerId: "editor", editorKey: "ek_your_key" });

6. Trying to npm install @dragble/editor-sdk

The SDK is CDN-only. There is no npm package for the SDK itself. Framework wrappers load it from CDN automatically.

7. Forgetting to destroy

In SPAs, always destroy the editor when the component unmounts. Framework wrappers handle this automatically, but in vanilla JS you must call destroy() manually.

// On route change or cleanup
editor.destroy();

Troubleshooting

Blank editor (white iframe)

1. Check that the container element exists in the DOM when init() or the component mounts.
2. Ensure the container has a non-zero height (height: 800px, not height: 0).
3. Check the browser console for CSP (Content Security Policy) errors blocking the iframe or SDK script.
4. Verify the editorKey is valid and not expired.

editor:ready never fires

1. Check the browser console for network errors loading the SDK from sdk.dragble.com.
2. Ensure the editorKey format is correct (ek_* or px_*).
3. Check that no ad blocker or firewall is blocking requests to sdk.dragble.com or the editor domain.
4. If using sdkUrl or editorUrl, verify the URLs are reachable and serve the correct files.

Ref is undefined (React)

The ref is populated after the component mounts and the SDK loads. Use onReady instead of checking the ref immediately:

// WRONG
useEffect(() => {
  editorRef.current?.editor?.exportHtml(); // ref not ready yet
}, []);

// RIGHT
<DragbleEditor
  ref={editorRef}
  => {
    // Safe to use editor here
  }}
/>

Design doesn't load

1. Ensure the design JSON is a valid Dragble DesignJson object (not a string -- parse it first if stored as a string).
2. If passing design as a prop, it loads at init time. If calling loadDesign() manually, wait for editor:ready.
3. Check that the design was exported from the same editor mode (email designs won't load correctly in web mode).

"Failed to load Dragble SDK" error

1. Check network connectivity to sdk.dragble.com.
2. If behind a corporate proxy, ensure the CDN domain is allowlisted.
3. If using a custom sdkUrl, verify the URL returns a valid JavaScript file.

Editor re-initializes on every render (React)

In React, the editor re-initializes when editorKey or containerId changes. Ensure these are stable values:

// WRONG: new key on every render
<DragbleEditor editorKey={`ek_${Date.now()}`} />

// RIGHT: stable key
<DragbleEditor editorKey="ek_your_stable_key" />

Callback props (onReady, onChange, etc.) are stored in refs internally and do NOT trigger re-initialization when they change.

Multiple editors interfere with each other

Each editor instance must have a unique container element. Framework wrappers auto-generate unique container IDs. In vanilla JS, ensure each containerId is unique and use createEditor() (not dragble.init()).