Options configurable in Topol Options

Topol options are used to set features which Topol provides. Pass them under the config property when creating the editor; callbacks are passed as top-level properties next to config (see the Callbacks Reference below).

Options are validated

The editor validates config against its options schema on initialization and on every setOptions() call. A value of the wrong type (for example colors: "#000" instead of ["#000"]) makes the editor throw an Invalid options provided error that names the offending field, and the editor does not start (or the setOptions() call is rejected). Unknown keys are not an error - they are silently ignored.

Options Reference

authorizeobjectrequired

Required credentials to initialize the editor securely. Learn more

aiLabeledElementsboolean default: false

Adds an AI content text field to every section and block, stored on the element as aiGenerateContent for your own AI pipeline. Learn more

apiIAPI

Custom API endpoints for backend integration. Learn more

apiAuthorizationHeaderstring | object

Authorization header sent with requests to your custom API endpoints. Learn more

autosaveIntervalnumber

Interval in seconds between autosave attempts. Learn more

colorsstring[]

Custom color palette for the color picker. Learn more

contentBlocksobject

Controls which block types are available (disable or hide individual blocks). Learn more

currentUserIOptionsUser

Information about the current user for comments and collaboration. Learn more

customBlocksarray

Custom block definitions with specific behavior or integrations. Learn more

customFileManagerboolean default: false

Enables custom file manager mode for your own upload workflow. Learn more

customFontsobject

Custom fonts available in the editor. Learn more

defaultTemplateSettingsobject

Typography, colors, and element defaults applied to a newly created page. Learn more

disableAiAssistantboolean default: false

Disables the AI assistant feature. Learn more

disableAlertsboolean default: false

Disables editor alert notifications. Learn more

enableAutosavesboolean default: false

Enables automatic saving at regular intervals. Learn more

enableCommentsboolean default: false

Enables the commenting system for collaboration. Learn more

enableFileManagerInGifboolean default: false

Allows picking GIF images through the file manager. Learn more

fileManagerPreferencesobject

UI preferences for the built-in file manager. Learn more

fontSizesnumber[]

Available font sizes in the editor. Learn more

hideSelectionPanelboolean default: false

Collapses the right-side selection panel (properties of the selected element). Learn more

hideSelectionPanelExpandboolean default: false

Hides the expand control on the selection panel. Learn more

hideSettingsTabboolean default: false

Hides the settings tab in the editor. Learn more

hideTopbarControlsstring[]

Hides specific controls from the top bar. Learn more

htmlMinifiedboolean default: false

Outputs minified HTML on export. Learn more

imageCompressionOptionsobject

Configures automatic image compression settings (defaults in the callout below). Learn more

imageEditorOptionsobject

Options for the built-in image editor, e.g. hiding specific controls. Learn more

imageMaxSizenumber default: 2097152 (2 MB)

Maximum allowed image upload size in bytes. Learn more

languagestring default: "en"

Editor UI language code (two-letter, from the supported list). Learn more

lightboolean default: false

Enables light theme mode. Learn more

premadeBlocksobject | array | false

Configuration for the premade design blocks library. Pass false to disable it entirely. Learn more

premadeTemplatesboolean default: false

Enables the premade template library. Learn more

premadeTemplatesOptionsobject

UI options for the premade template library (hideSearch; showDelete is accepted but has no effect). Learn more

removeTopBarboolean default: false

Removes the top bar completely. Learn more

renameTemplateboolean default: false

Enables template renaming functionality. Learn more

rolestring

User role determining permissions (manager, editor, reader). Learn more

savedBlocksboolean default: false

Enables the saved blocks library. Learn more

showUnsavedDialogBeforeExitboolean default: true

Enabled by default. Set to false to suppress the browser confirmation dialog when leaving with unsaved changes. Learn more

syncedSectionsEnabledboolean default: false

Enables synced sections across multiple pages. Learn more

teamUsersIOptionsUser[]

Team members available for @mentions in comments. Learn more

templateIdstring | number

Template identifier used for comments and other API features. Learn more

textOverrideobject

Custom text overrides for UI labels. Currently applied only when language is not set. Learn more

themeobject default: dark preset

Custom theme configuration for editor appearance. Learn more

titlestring

Template title shown in the window bar. Only visible when windowBar or renameTemplate is set. Learn more

windowBarstring[]

Controls displayed in the window bar. Learn more

Defaults worth knowing

imageCompressionOptions defaults: qualityJpeg: 0.95, qualityPng: 0.8, enableAutoResize: true, enableCompression: true.
When theme is not set, the editor uses the dark preset; theme.preset: "light" also switches the light option on, so the two interact.
Supported language codes: en, fr, pt, es, ja, zh, ru, tr, de, sv, nl, it, fi, ro, cs, pl, ko, vi, he, ar. Regional variants such as en-US are not supported - an unsupported code fails options validation and the editor does not start.

Callbacks Reference

Callbacks are passed as top-level properties when creating the editor, next to config - not inside the options object:

const editor = LandingPageEditor({
  config: { authorize: { apiKey: "YOUR_API_KEY", userId: "user-123" } },
  onSave({ json, html }) {
    /* ... */
  },
});

One payload object per callback

Every callback receives at most one argument: an object with named properties (onSave({ json, html }), onUndoChange({ count }), onEditorError({ source, message, detail }), ...). Callbacks that carry no data (onInit, onLoaded, onPreviewClose, ...) are called with no arguments. New fields can be added to a payload later without breaking your handlers, so destructure what you need and ignore the rest.

onSave({ json, html }) => void | Promise<void>

Called when user saves the template. json is the template definition, html the rendered page as a string. May return a Promise: the editor keeps its saving state until it settles, and a rejection is shown as a save error - so an async handler that persists to your backend reports failures to the user for free. A Promise that never settles is released after 30 seconds with a console warning. Learn more

onSaveAndClose({ json, html }) => void | Promise<void>

Called when user saves and closes the editor. Same payload and Promise handling as onSave; a rejection keeps the editor open. Closing the editor UI is your job in this handler. When you do not define onSaveAndClose, the payload goes to onSave instead and the editor iframe is removed by the loader afterwards.

onOpenFileManager()

Called when file manager should open. Learn more

onImageDelete({ items })

Called when files or folders are deleted in the file manager, so you can clean up your own storage.

onLoaded()

Called after a template passed to load() has been applied.

onInit()

Called once the editor is fully initialized and ready.

onUndoChange({ count })

Called when undo history changes. count is the number of undo steps available.

onRedoChange({ count })

Called when redo history changes. count is the number of redo steps available.

onPreview({ html })

Called when user triggers preview mode. html is the rendered page as a string.

onPreviewClose()

Called when the preview is closed.

onAlert({ notification })

Called when editor displays an alert. notification carries type, text and the other notification fields. Learn more

onEditorClose() => void | Promise<void>

Called when the user closes the editor from the window bar (the close button is enabled with windowBar). Closing the editor UI is your job in this handler; when you do not define it, the editor iframe is removed by the loader instead. May return a Promise. Named onEditorClose because the loader reserves onClose for its own lifecycle.

onEdittedWithoutSaveChanged({ value })

Called when the unsaved-changes state flips. value is true while there are unsaved edits.

onOpenCustomBlockDialog({ block })

Called when custom block dialog should open. block is the custom block data including its current content. Learn more

onTemplateRename({ name })

Called when user clicks the rename button. name is the current template name. Learn more

onEditorError({ source, message, detail? })

Called when an error occurs in the editor. source is "authorize", "network" or "templateLoad", message a human-readable description and detail the raw error data when available (for network errors, the response body). Named onEditorError because the loader reserves onError for its own lifecycle.

TypeScript Interface

Options passed under config:

interface IPluginOptions {
  authorize: {
    apiKey: string;
    userId: string | number;
  };
  aiLabeledElements?: boolean;
  api?: IAPI;
  apiAuthorizationHeader?: Record<string, string> | string;
  autosaveInterval?: number;
  colors?: Array<string>;
  contentBlocks?: Partial<
    Record<
      | "text"
      | "image"
      | "gif"
      | "button"
      | "divider"
      | "spacer"
      | "social"
      | "video"
      | "form"
      | "html"
      | "raw"
      | "custom-raw",
      {
        disabled?: boolean;
        disabledText?: string;
        hidden?: boolean;
        disabledBadge?: string;
      }
    >
  >;
  currentUser?: IOptionsUser;
  customBlocks?: TopolCustomBlockData[];
  customFileManager?: boolean;
  customFonts?: {
    override?: boolean;
    fonts: Array<IFont>;
  };
  defaultTemplateSettings?: TopolTemplateSettings;
  disableAiAssistant?: boolean;
  disableAlerts?: boolean;
  enableAutosaves?: boolean;
  enableComments?: boolean;
  enableFileManagerInGif?: boolean;
  fileManagerPreferences?: {
    defaultTilesView?: boolean;
    hidePexelsIntegration?: boolean;
    maxUploadingFiles?: number; // positive integer
  };
  fontSizes?: Array<number>;
  hideSelectionPanel?: boolean;
  hideSelectionPanelExpand?: boolean;
  hideSettingsTab?: boolean;
  hideTopbarControls?: Array<string>;
  htmlMinified?: boolean;
  imageCompressionOptions?: {
    qualityJpeg?: number;
    qualityPng?: number;
    enableAutoResize?: boolean;
    enableCompression?: boolean;
  };
  imageEditorOptions?: {
    hideControls?: Array<string>;
  };
  imageMaxSize?: number;
  language?: ILanguage;
  light?: boolean;
  premadeBlocks?: IOptionsPremadeBlock;
  premadeTemplates?: boolean;
  premadeTemplatesOptions?: {
    hideSearch?: boolean;
    showDelete?: boolean;
  };
  removeTopBar?: boolean;
  renameTemplate?: boolean;
  role?: "manager" | "editor" | "reader";
  savedBlocks?: boolean;
  showUnsavedDialogBeforeExit?: boolean;
  syncedSectionsEnabled?: boolean;
  teamUsers?: IOptionsUser[];
  templateId?: number | string;
  textOverride?: Record<string, string>;
  theme?: ITheme;
  title?: string;
  windowBar?: Array<string>;
}

type ILanguage =
  | "en" | "fr" | "pt" | "es" | "ja" | "zh" | "ru" | "tr" | "de" | "sv"
  | "nl" | "it" | "fi" | "ro" | "cs" | "pl" | "ko" | "vi" | "he" | "ar";

interface IOptionsUser {
  userId: string; // must be a string here, unlike authorize.userId
  name: string;
  profilePhotoUrl: string;
}

interface IFont {
  label: string;
  style: string;
  url?: string;
}

// premadeBlocks accepts one of four shapes:
type IOptionsPremadeBlock =
  | { blocks: PremadeBlocks | LegacyPremadeBlocks; override: boolean }
  | Array<{ id?: number; name: string; blocks: PremadeBlock[] }>
  | { content?: unknown; ecomm?: unknown; footers?: unknown; headers?: unknown }
  | false; // disables premade blocks entirely

Callbacks are passed as top-level properties alongside config:

interface ISavePayload {
  json: object; // template definition
  html: string; // rendered page
}

interface IDeletedItem {
  name: string;
  type: "file" | "folder";
  path: string;
  url?: string;
  key: string | null;
}

interface ILandingPageEditorProps {
  config: IPluginOptions;
  onSave?(payload: ISavePayload): void | Promise<void>;
  onSaveAndClose?(payload: ISavePayload): void | Promise<void>;
  onOpenFileManager?(): void;
  onImageDelete?(payload: { items: IDeletedItem[] }): void;
  onLoaded?(): void;
  onInit?(): void;
  onUndoChange?(payload: { count: number }): void;
  onRedoChange?(payload: { count: number }): void;
  onPreview?(payload: { html: string }): void;
  onPreviewClose?(): void;
  onAlert?(payload: { notification: INotification }): void;
  onEditorClose?(): void | Promise<void>;
  onEdittedWithoutSaveChanged?(payload: { value: boolean }): void;
  onOpenCustomBlockDialog?(payload: { block: unknown }): void;
  onTemplateRename?(payload: { name: string }): void;
  onEditorError?(payload: {
    source: "authorize" | "network" | "templateLoad";
    message: string;
    detail?: unknown;
  }): void;
}

Common pitfall

Do not wrap callbacks in a callbacks: { ... } object inside config - the editor ignores that key entirely and no callback will ever fire. Always pass callbacks as top-level properties next to config.

INFO

defaultTemplateSettings nested fields are all optional and merge over the built-in defaults; invalid values are silently dropped rather than raising an error. Learn more

Options configurable in Topol Options ​

Options Reference ​

Callbacks Reference ​

TypeScript Interface ​

Options configurable in Topol Options

Options Reference

Callbacks Reference

TypeScript Interface