Configuration

Complete reference for all DragbleConfig / EditorOptions properties passed when initializing the editor.

Initialization Options

These are the top-level properties passed to dragble.init() or the framework component:

Option	Type	Required	Default	Description
containerId	string	Yes	—	The DOM element ID to mount the editor.
editorKey	string	Yes	—	Editor key for authentication (from the Dragble Dashboard). Starts with db_.
editorVersion	string	No	'latest'	Editor version channel or exact semver. See Version Management.
editorUrl	string	No	—	Full editor URL override for self-hosting. When set, editorVersion is ignored.
editorMode	'email' | 'web' | 'popup'	No	'email'	Builder mode.
designMode	'edit' | 'live'	No	'live'	Admin vs end-user permissions.
design	DesignJson | null	No	—	Initial design to load.
popup	PopupConfig	No	—	Popup builder configuration (required when editorMode is 'popup').
callbacks	DragbleCallbacks	No	{}	Lifecycle and action callbacks. See Callbacks.
options	EditorOptions	No	{}	All editor configuration (see below).

Editor Options

These are nested under options in the SDK's DragbleConfig:

Option	Type	Required	Default	Description
user	UserConfig	Yes	—	Current user identity.
locale	string	No	'en-US'	BCP 47 locale for the editor UI (e.g. 'fr-FR', 'de-DE', 'ja-JP'). Supports 29 built-in languages.
translations	Record<string, Record<string, string>>	No	{}	Custom translation overrides keyed by locale.
textDirection	'ltr' | 'rtl'	No	'ltr'	Text direction for the editor UI and content.
mergeTags	MergeTag[]	No	[]	Dynamic merge tags available in the text editor (e.g. {{first_name}}).
designTags	Record<string, string>	No	{}	Key/value pairs replaced in HTML at export time.
specialLinks	SpecialLink[]	No	[]	Custom link types shown in the link picker (e.g. unsubscribe, view-in-browser).
modules	Module[]	No	[]	Reusable modules available in the Modules Library. Categories are normalized to lowercase.
displayConditions	DisplayCondition[]	No	[]	Conditions users can apply to rows for conditional rendering.
appearance	AppearanceConfig	No	{}	Theme, accent color, and layout settings.
tools	ToolsConfig	No	{}	Show, hide, or lock individual content tools.
customTools	CustomTool[]	No	[]	Register custom content tools.
fonts	FontDefinition[]	No	[]	Custom fonts available in the editor.
bodyValues	BodyValues	No	{}	Default body-level values (background color, content width, font family).
header	DesignJson	No	—	Locked header row rendered above the editable area.
footer	DesignJson	No	—	Locked footer row rendered below the editable area.
editor	EditorConfig	No	{}	Editor behavior settings.
features	FeaturesConfig	No	{}	Enable/disable editor features.
assetStorage	AssetStorageConfig	No	—	Image/file upload configuration.
ai	AIConfig	No	{ mode: 'disabled' }	AI feature configuration. See AI Overview.
callbacks	DragbleCallbacks	No	{}	Lifecycle and action callbacks. See Callbacks.

UserConfig

interface UserConfig {
  id: string;
  name: string;
  email: string;
  avatar?: string; // URL to avatar image
}

AppearanceConfig

Option	Type	Default	Description
theme	'light' | 'dark' | 'auto' | 'dragble-light' | 'dragble-dark'	'light'	Editor color theme. auto follows system preference. dragble-* themes use fixed brand colors.
accentColor	AccentColor	'indigo'	Accent color name from Radix UI color scales. See Customize Appearance for the full list.
sidePanel	SidePanelConfig	{}	Side panel configuration (dock, width, tabs, collapsible, etc.).
panels	PanelsConfig	{}	Legacy panel config — prefer sidePanel.
loader	LoaderConfig	—	Custom loader configuration (svg > url > html + css > default spinner).
features	{ preview?: boolean; undoRedo?: boolean }	{}	Deprecated — use top-level FeaturesConfig instead.
customStyles	Record<string, string>	{}	Custom CSS variables.
actionBar	ActionBarConfig	{ placement: 'bottom_right' }	Floating action bar for row/content selection.
shortcutBar	ShortcutBarConfig	{ placement: 'top_left' }	Floating shortcut bar (preview, undo/redo, responsive toggles).

SidePanelConfig

Configure the side panel under options.appearance.sidePanel:

interface SidePanelConfig {
  dock?: "left" | "right";
  width?: number;
  collapsible?: boolean;
  accordionsCollapsed?: boolean;
  tabs?: {
    content?: { visible?: boolean };
    modules?: { visible?: boolean };
    styles?: { visible?: boolean };
  };
  modulesTab?: {
    rows?: { visible?: boolean; defaultExpanded?: boolean };
    modulesLibrary?: ModulesLibraryConfig;
  };
}

interface ModulesLibraryConfig {
  visible?: boolean;
  defaultExpanded?: boolean;
  title?: string; // default: "Modules Library"
  categories?: string[];
  defaultCategory?: string;
}

Example:

const config: DragbleConfig = {
  options: {
    appearance: {
      sidePanel: {
        modulesTab: {
          modulesLibrary: {
            title: "Brand Modules",
            categories: ["Banner", "POPULAR", "footer"],
            defaultCategory: "Banner",
          },
        },
      },
    },
  },
};

The SDK/editor normalizes module categories to lowercase on load and save. In the example above, "Banner", "banner", and "BANNER" all become banner; the UI displays category labels capitalized.

ToolsConfig

Controls visibility and behavior of content tools in the sidebar:

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)
}

EditorConfig

Option	Type	Default	Description
minRows	number	1	Minimum number of rows in the design.
maxRows	number | null	null	Maximum number of rows allowed. null means unlimited.
contentType	'module'	—	Set to 'module' to restrict the editor to single-module editing mode.
autoSelectOnDrop	boolean	false	Automatically select a content block after it is dropped into the canvas.
confirmOnDelete	boolean	false	Show a confirmation dialog before deleting rows or content.
rows	boolean	true	Show/hide the Rows accordion in the Modules tab.
title	string	—	Title displayed in the editor header area.

FeaturesConfig

Option	Type	Default	Description
preview	boolean	true	Show/hide the preview button.
undoRedo	boolean	true	Show/hide undo/redo buttons.
responsiveDesign	boolean	true	Show/hide responsive design toggle.
userUploads	boolean	true	Enable user image uploads.
fileManager	boolean	true	Show File Manager modal. When false, "Choose Image" is hidden but direct upload remains available.
imageEditor	boolean	undefined	Enable built-in image cropping/editing. When false, explicitly disables even if the plan allows it. When undefined/true, defers to plan-level permission.
stockImages	boolean | StockImagesConfig	true	Enable stock image browser in the file manager. Pass an object for additional options (safeSearch, defaultSearchTerm).
modules	boolean | ModuleFeaturesConfig	false	Enable modules feature (save row as module, synced modules). Pass an object for granular control (saveRowAsModule).
specialLinks	boolean	true	Show special links in the text editor toolbar.
smartMergeTags	boolean	false	Enable smart merge tags.
languageSelector	boolean	true	Show language selector dropdown in the side panel. When false, language is controlled externally via SDK.
audit	boolean	false	Enable content quality audit checks.
amp	boolean	false	Enable AMP for Email in email mode. When enabled and the plan allows AMP, email mode unlocks interactive tools and exportHtml() returns AMP HTML.
header	boolean	false	Enable locked header row injected from SDK. Requires plan to allow core.header.
footer	boolean	false	Enable locked footer row injected from SDK. Requires plan to allow core.footer.
preheaderText	boolean	true	Show the preheader text input in the Styles panel (email mode only).
dynamicImage	boolean	undefined	Enable dynamic image feature on the image tool. Lets users set merge-tag URLs that replace the image source at send time. When false, explicitly disables even if the plan allows it.
export	ExportFeaturesConfig	{}	Granular export feature toggles: { html?, json?, image?, pdf?, zip?, amp? }.

AssetStorageConfig

Option	Type	Description
uploadUrl	string	URL to POST image uploads to.
uploadHeaders	Record<string, string>	Additional headers sent with upload requests.
onUpload	(file: File) => Promise<{ url: string }>	Custom upload handler (overrides uploadUrl).
maxFileSize	number	Max file size in bytes (default: 5MB).
acceptedFormats	string[]	Accepted MIME types (default: ['image/png', 'image/jpeg', 'image/gif', 'image/webp']).

AIConfig

Option	Type	Description
mode	'dragble' | 'external' | 'disabled'	AI mode. See AI Overview.
features	AIFeaturesConfig	Enable/disable individual AI features.
callbacks	AICallbacks	Callback handlers for external mode.

Example: Full Configuration

const config: DragbleConfig = {
  user: { id: "1", name: "Jane Doe", email: "jane@example.com" },
  locale: "en-US",
  textDirection: "ltr",
  mergeTags: [
    { label: "First Name", value: "{{first_name}}" },
    { label: "Company", value: "{{company}}" },
  ],
  appearance: {
    theme: "light",
    accentColor: "indigo",
  },
  tools: {
    html: { enabled: false },
    video: { enabled: false },
  },
  editor: {
    minRows: 1,
    maxRows: 50,
    confirmOnDelete: true,
  },
  features: {
    userUploads: true,
    fileManager: true,
    export: { pdf: false },
  },
  assetStorage: {
    onUpload: async (file) => {
      const form = new FormData();
      form.append("file", file);
      const res = await fetch("/api/upload", { method: "POST", body: form });
      return res.json();
    },
  },
  ai: { mode: "dragble" },
};

info

Options not specified use their default values. At the top level, containerId and editorKey are required. Within options, only user is required.