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:

plaintext
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.

ts
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.

ts
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

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

ThemeMode

ts
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:

ts
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

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

BuiltInLocaleCode

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

ts
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.

ts
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":

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

ExportHtmlData

Returned by exportHtml().

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

ExportImageData

Returned by exportImage().

ts
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().

ts
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().

ts
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.

ts
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

ts
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

ts
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;
}

interface ModulesTabConfig {
  rows?: { visible?: boolean; defaultExpanded?: boolean };
  modulesLibrary?: {
    visible?: boolean;
    defaultExpanded?: boolean;
    title?: string; // default: "Modules Library"
    categories?: string[]; // normalized to lowercase
    defaultCategory?: string; // normalized to lowercase
  };
}

ActionBarConfig

ts
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

ts
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

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

MergeTag

ts
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

ts
interface Module {
  id: string;
  name: string;
  category: string; // category for grouping; normalized to lowercase
  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
}

Module categories are canonical lowercase values. If you pass "Banner", "banner", or "BANNER", the SDK/editor stores and returns "banner". The editor UI displays category labels with capitalization.

FontDefinition

ts
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

ts
// 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:

ts