TFrameEvents

Event handler map for the ONLYOFFICE Apps iframe. Passed via TFrameConfig.events. All handlers are optional — set to null (default) to disable.

Events are delivered from the iframe to the host via the onEventReturn postMessage type. Each handler's description names the modes that emit the event; an event the portal sends without data reaches the handler as an empty object ({}).

type TFrameEvents = object;

Example

sdk.init({
  events: {
    onAppReady: () => console.log("ONLYOFFICE Apps loaded"),
    onAppError: (err) => console.error("Init error:", err),
    onSelectCallback: (item) => console.log("Selected:", item),
  },
  ...
});

Properties

Property	Type	Description
onAppError	null | ((message: string) => void)	Fired in every mode. The SDK fires it on a CSP, message parsing, connection or method timeout failure; the frame fires it with its own message when a page fails to load (e.g. the chat). Receives the error message string. A token failure fires TFrameEvents.onAuthError instead, and a portal API error does not fire it: the method's promise rejects.
onAppReady	null | ((data: TAppReadyPayload) => void)	Fired once, in every mode, when the ONLYOFFICE Apps frame is fully initialized and ready. SDKMode.PublicRoom without a valid TFrameConfig.id renders an "Invalid link" page and never fires it.
onAuthError	null | ((error: TAuthError) => void)	Fired in OAuth mode only, when no access token can be used. Receives a TAuthError whose code names the failure: the SDK could not resolve a token, the frame waited for one in vain, or the portal rejected it. The host should re-authenticate the user or destroy the frame; the frame itself shows a loader and never a sign-in page.
onAuthSuccess	null | ((data: object) => void)	Fired when the user completes a sign-in through a confirmation link opened inside the frame. Not fired by SDKInstance.login or the OAuth flow, where TFrameEvents.onAppReady is the sign of success.
onCloseCallback	null | (() => void)	Fired in selector modes (SDKMode.RoomSelector, SDKMode.FileSelector) when the dialog is closed or canceled.
onContentReady	null | (() => void)	Fired when the iframe content is fully loaded and visible, in every mode. With TFrameConfig.noLoader true the SDK fires it on the iframe's load event, otherwise when the portal calls SDKInstance.setIsLoaded; its order relative to TFrameEvents.onAppReady is not guaranteed.
onCustomAction	| null | ((data: TCustomActionEvent) => void)	Fired when a custom action from TFrameConfig.customActions or SDKInstance.setCustomActions is clicked in SDKMode.Manager, SDKMode.Personal or SDKMode.Forms. Receives a TCustomActionEvent.
onDownload	null | ((url: string) => void)	Fired on file download when TFrameConfig.downloadToEvent is true, in SDKMode.Manager, SDKMode.PublicRoom and SDKMode.Personal. Receives the download URL.
onEditorCloseCallback	null | (() => void)	Fired in SDKMode.Editor and SDKMode.Viewer when the document editor is closed (via UI button, hotkey, or programmatically) while TFrameConfig.editorGoBack is "event".
onEditorOpen	| null | ((file: TEditorOpenPayload) => void)	Fired in SDKMode.Manager, SDKMode.PublicRoom and SDKMode.Personal when the user opens a file from the list (row activation, context menu, hotkey), and in SDKMode.Manager also for a document created from the "Create" dialog. Not fired by SDKMode.Forms, which embeds the editor in the frame, and not for a newly created document in SDKMode.PublicRoom and SDKMode.Personal (ONLYOFFICE Apps 4.0), where the portal opens its editor itself. Receives the file with the requested action — see TEditorOpenPayload. Registering the handler suppresses the portal's own editor: open the file in a frame of your own.
onFileManagerClick	null | ((file: TFileInfo) => void)	Fired in SDKMode.Manager, SDKMode.PublicRoom, SDKMode.Forms and SDKMode.Personal when a file row is activated in the list. Files only — a folder click navigates into the folder instead. Receives the portal's file object (TFileInfo). Registering the handler suppresses the portal's own open action.
onFilterSearch	| null | ((data: TFilterSearchPayload) => void)	Fired in SDKMode.Personal and SDKMode.PublicRoom when the search text of the file list changes, and with an empty string when the search is reset. Receives a TFilterSearchPayload.
onGetExternalData	| null | ((req: TGetExternalDataRequest) => unknown | Promise<unknown>)	Fired when the ONLYOFFICE Apps iframe asks the host to read a value from external storage. The integrator returns the value currently stored for the given key (sync or Promise); the SDK posts it back to the iframe, correlating the response by callId. The meaning of key and the shape of the returned value are defined by the integrator — the SDK treats the payload as opaque. If the handler throws or its promise rejects, the error is routed to TFrameEvents.onAppError and no response is sent.
onNavigate	null | ((data: TNavigatePayload) => void)	Fired when the user navigates to a different section in SDKMode.Forms or SDKMode.Personal. Receives the active section.
onNoAccess	null | (() => void)	Fired in SDKMode.Manager and SDKMode.PublicRoom when navigating to an inaccessible or deleted room/folder, and in SDKMode.Chat when the frame has no signed-in, non-guest user.
onNotFound	null | (() => void)	Fired in SDKMode.Manager and SDKMode.PublicRoom when navigating to a non-existent room/folder (404).
onSelectCallback	| null | ((selection: | TSelectedRoom[] | TSelectedFile) => void)	Fired in selector modes when a room or file is selected. SDKMode.RoomSelector passes an array of TSelectedRoom (one element for a single choice); SDKMode.FileSelector passes a single TSelectedFile object.
onSetExternalData	| null | ((payload: TSetExternalDataPayload) => void | Promise<void>)	Fired when the ONLYOFFICE Apps iframe asks the host to persist a value in external storage. Fire-and-forget: the SDK does not post a response back to the iframe. The handler may return a Promise; if the promise rejects (or the handler throws), the error is routed to TFrameEvents.onAppError. The meaning of key and value is defined by the integrator — typically value is an object with user-scoped key/value pairs.
onSignOut	null | (() => void)	Fired when the user signs out through the portal's profile menu inside the frame. Not fired by SDKInstance.logout. In OAuth mode the frame then stops asking for tokens until it is loaded again.
onUploadError	| null | ((data: | TUploadError | TUploaderUploadError) => void)	Fired when an upload fails. SDKMode.Uploader: a TUploaderUploadError for the dialog's own upload, including files refused by validation. SDKMode.Forms and SDKMode.Personal: a TUploadError for a file transferred with SDKInstance.upload.
onUploadProgress	null | ((data: TUploadProgress) => void)	Fired in SDKMode.Uploader only, after every uploaded chunk of every file of the dialog's own upload. Receives a TUploadProgress. Not fired for SDKInstance.upload.
onUploadSuccess	| null | ((data: | TUploadResult | TUploaderUploadResult[]) => void)	Fired when files are stored. SDKMode.Uploader: once per batch of the dialog's own upload, with an array of TUploaderUploadResult. SDKMode.Forms and SDKMode.Personal: once per file transferred with SDKInstance.upload, with a TUploadResult; the frame's own upload UI does not fire it there.