TypeScript Types

Key types for using the Dragble SDK with TypeScript.

Using with CDN

Since the SDK loads via CDN, add type declarations to your project:

src/dragble.d.ts

declare const dragble: {
  createEditor(config: DragbleConfig): Promise<DragbleEditorInstance>;
};

interface DragbleConfig {
  containerId: string;
  editorKey?: string;
  editorMode?: "email" | "web";
  user?: { id: string; name: string; email: string };
  appearance?: { theme?: "light" | "dark"; accentColor?: string };
}

interface DragbleEditorInstance {
  loadDesign(design: DesignJson): void;
  getDesign(): DesignJson;
  exportHtml(): Promise<ExportHtmlData>;
  addEventListener(event: string, handler: Function): void;
  removeEventListener(event: string, handler: Function): void;
  destroy(): void;
}

DesignJson

The serializable design document. This is what you save to your database and load back into the editor.

interface DesignJson {
  body: {
    id: string;
    rows: Row[];
    headers?: Row[];
    footers?: Row[];
    values: BodyValues;
  };
  counters?: Record<string, number>;
  schemaVersion: number;
  _meta?: DesignMeta;
}

BodyValues

Body-level styling and layout values.

interface BodyValues {
  backgroundColor?: string;
  contentWidth?: string; // e.g. '600px'
  contentAlignment?: "center" | "left";
  fontFamily?: string;
  fontSize?: string;
  textColor?: string;
  linkColor?: string;
  preheaderText?: string;
  padding?: string; // e.g. '20px 0'
  borderRadius?: string;
  _meta?: Record<string, any>;
}

EditorMode

type EditorMode = "email" | "web" | "popup";

ThemeMode

type ThemeMode = "light" | "dark" | "auto" | "dragble-light" | "dragble-dark";

The light and dark themes respect the accentColor setting. The dragble-light and dragble-dark themes use fixed brand colors and ignore accentColor. The auto theme follows the system preference.

AccentColor

25 accent colors based on Radix UI color scales:

type AccentColor =
  | "gray"
  | "gold"
  | "bronze"
  | "brown"
  | "yellow"
  | "amber"
  | "orange"
  | "tomato"
  | "red"
  | "ruby"
  | "crimson"
  | "pink"
  | "plum"
  | "purple"
  | "violet"
  | "iris"
  | "indigo"
  | "blue"
  | "cyan"
  | "teal"
  | "jade"
  | "green"
  | "grass"
  | "mint"
  | "sky";

ViewMode

type ViewMode = "desktop" | "tablet" | "mobile";

BuiltInLocaleCode

All 29 built-in locale codes supported by the editor. See Localization for the full language table.

type BuiltInLocaleCode =
  | "en-US"
  | "en-CA" // English (USA, Canada)
  | "ar-AE" // Arabic (UAE) — RTL
  | "zh-CN"
  | "zh-TW" // Chinese (Simplified, Traditional)
  | "cs-CZ" // Czech
  | "da-DK" // Danish
  | "nl-NL" // Dutch
  | "et-EE" // Estonian
  | "fa-IR" // Farsi / Persian — RTL
  | "fi-FI" // Finnish
  | "fr-FR"
  | "fr-CA" // French (France, Canada)
  | "de-DE" // German
  | "hu-HU" // Hungarian
  | "id-ID" // Indonesian
  | "it-IT" // Italian
  | "ja-JP" // Japanese
  | "ko-KR" // Korean
  | "no-NO" // Norwegian
  | "pl-PL" // Polish
  | "pt-BR"
  | "pt-PT" // Portuguese (Brazil, Portugal)
  | "ru-RU" // Russian
  | "es-ES" // Spanish
  | "sv-SE" // Swedish
  | "tr-TR" // Turkish
  | "uk-UA" // Ukrainian
  | "vi-VN"; // Vietnamese

LocaleCode

Accepts any built-in locale or a custom string for user-provided translations.

type LocaleCode = BuiltInLocaleCode | (string & {});

tip

Using LocaleCode gives you autocomplete for all 29 built-in locales while still accepting custom locale strings like "th" or "he":

const config: DragbleConfig = {
  locale: "fr-FR", // ← autocomplete suggests all 29 built-in codes
};

ExportHtmlData

Returned by exportHtml().

interface ExportHtmlData {
  html: string; // fully rendered responsive HTML
  design: DesignJson; // the design at export time
}

ExportImageData

Returned by exportImage().

interface ExportImageData {
  url?: string; // hosted URL (when saveToStorage is true)
  imageData?: string; // base64 image data
}

interface ExportImageOptions {
  format?: "png" | "jpg";
  width?: number;
  height?: number | null;
  fullPage?: boolean;
  quality?: number; // 0–1
  deviceScaleFactor?: number; // pixel density multiplier (default: 1)
  saveToStorage?: boolean; // save to Dragble storage and return URL
  mergeTags?: Record<string, string>; // merge tag values for rendering
}

ExportPdfData

Returned by exportPdf().

interface ExportPdfData {
  url?: string; // hosted URL (when saveToStorage is true)
  pdfData?: string; // base64 PDF data
}

interface ExportPdfOptions {
  pageSize?: "full" | "letter" | "a4" | "a3";
  orientation?: "portrait" | "landscape";
  printBackground?: boolean;
  margin?: { top?: string; right?: string; bottom?: string; left?: string };
  saveToStorage?: boolean;
  mergeTags?: Record<string, string>;
}

ExportZipData

Returned by exportZip().

interface ExportZipData {
  zipData?: string; // base64 ZIP data
}

interface ExportZipOptions {
  imageFolder?: string; // folder name for images inside the ZIP
}

DragbleConfig

Top-level configuration object. See Configuration for details on each property.

interface DragbleConfig {
  user: UserConfig;
  locale?: LocaleCode; // default: 'en-US'
  translations?: Record<string, Record<string, string>>;
  textDirection?: "ltr" | "rtl";
  mergeTags?: MergeTag[];
  designTags?: Record<string, string>;
  specialLinks?: SpecialLink[];
  modules?: Module[];
  displayConditions?: DisplayCondition[];
  appearance?: AppearanceConfig;
  tools?: ToolsConfig;
  customTools?: CustomTool[];
  fonts?: FontDefinition[];
  bodyValues?: BodyValues;
  header?: DesignJson;
  footer?: DesignJson;
  editor?: EditorConfig;
  features?: FeaturesConfig;
  assetStorage?: AssetStorageConfig;
  ai?: AIConfig;
  callbacks?: DragbleCallbacks;
}

ToolsConfig

interface ToolsConfig {
  [key: string]: ToolConfig | undefined;
  // Built-in tool keys: paragraph, text, heading, button, image,
  // divider, menu, html, social, video, table, timer, form, spacer
}

interface ToolConfig {
  enabled?: boolean; // show/hide the tool (default: true)
  position?: number; // order in the content panel
  properties?: Record<string, ToolPropertyConfig>;
}

interface ToolPropertyConfig {
  value?: unknown; // default value for the property
  editable?: boolean; // whether the user can edit this property (default: true)
}

AppearanceConfig

interface AppearanceConfig {
  theme?: ThemeMode;
  accentColor?: AccentColor;
  sidePanel?: SidePanelConfig;
  panels?: PanelsConfig; // legacy — prefer sidePanel
  loader?: { html?: string; css?: string; svg?: string; url?: string };
  features?: { preview?: boolean; undoRedo?: boolean }; // deprecated — use FeaturesConfig
  customStyles?: Record<string, string>;
  actionBar?: ActionBarConfig;
  shortcutBar?: ShortcutBarConfig;
}

interface SidePanelConfig {
  dock?: "left" | "right";
  width?: number;
  collapsible?: boolean;
  accordionsCollapsed?: boolean; // default: false
  tabs?: {
    content?: { visible?: boolean };
    modules?: { visible?: boolean };
    styles?: { visible?: boolean };
  };
  modulesTab?: ModulesTabConfig;
  stylesTab?: StylesTabConfig;
}

ActionBarConfig

type ActionBarPlacement =
  | "top_left"
  | "top_right"
  | "bottom_left"
  | "bottom_right";

interface ActionBarConfig {
  /** Placement of the floating action bar (default: 'bottom_right') */
  placement?: ActionBarPlacement;
  /** Compact mode — smaller buttons (default: false) */
  compact?: boolean;
}

ShortcutBarConfig

type ShortcutBarPlacement =
  | "top_left"
  | "top_right"
  | "bottom_left"
  | "bottom_right";

interface ShortcutBarConfig {
  /** Placement of the shortcut bar in the workspace (default: 'top_left') */
  placement?: ShortcutBarPlacement;
}

AIConfig

interface AIConfig {
  mode: "dragble" | "external" | "disabled";
  features?: {
    smartText?: boolean;
    smartHeading?: boolean;
    smartButton?: boolean;
    imageGeneration?: boolean;
    imageSearch?: boolean;
    altText?: boolean;
  };
  callbacks?: AICallbacks;
}

MergeTag

interface MergeTag {
  label: string; // display label shown in dropdown
  value: string; // tag syntax, e.g. '{{first_name}}'
  category?: string; // category for grouping
  sample?: string; // sample value for preview
}

interface MergeTagGroup {
  name: string; // group name
  mergeTags: (MergeTag | MergeTagGroup)[]; // supports nested groups
}

Module

interface Module {
  id: string;
  name: string;
  category: string; // category for grouping (required)
  mode: "email" | "web"; // editor mode compatibility
  type: "standard" | "synced"; // 'synced' modules stay linked across designs
  data: unknown; // module design data (row JSON)
  html?: string; // rendered HTML preview
  thumbnail?: string; // URL or base64
  tags?: string[]; // search/filter tags
}

FontDefinition

interface FontDefinition {
  label: string;
  value: string; // CSS font-family value
  url?: string; // URL to @font-face CSS file
  weights?: number[]; // available weights, e.g. [400, 700]
}

Utility Types

// Editor error object
interface EditorError {
  code: string;
  message: string;
  details?: Record<string, any>;
}

// Validation
interface ValidationResult {
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
}

interface ValidationError {
  elementId: string;
  field: string;
  message: string;
}

interface ValidationWarning {
  elementId: string;
  field: string;
  message: string;
}

tip

Import types directly — they are type-only exports and add zero bytes to your bundle:

import type { DesignJson, DragbleConfig } from "dragble-types";