SDKInstance

Manages a single ONLYOFFICE Apps iframe, handles postMessage communication, and exposes methods for operating on the embedded ONLYOFFICE Apps UI.

Instances are created and stored by SDK. Do not construct directly — use SDK.init or any init* convenience wrapper.

note

Every method that talks to the frame returns a promise that rejects with an SDKError: SDKErrorCode.ApiError when the portal reports a failure (HTTP status in SDKError.status), SDKErrorCode.ModeMismatch when the current mode has no such method, SDKErrorCode.Timeout after TFrameConfig.methodTimeout and SDKErrorCode.Disconnected when the frame is not connected. Two legacy methods differ: SDKInstance.login and SDKInstance.createRoom resolve a portal failure as { status, message }. A portal older than ONLYOFFICE Apps 4.0 does not flag failures: there every method resolves the portal's error object instead of rejecting.

Example

import { SDK } from '@onlyoffice/docspace-sdk-js';

const sdk = new SDK();
const instance = sdk.initManager({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
});

instance.getUserInfo().then((user) => console.log(user));

Constructors

Constructor

new SDKInstance(config: TFrameConfig): SDKInstance;

Parameters

Parameter	Type	Description
`config`	`TFrameConfig`	Initial frame configuration. See TFrameConfig.

Returns

SDKInstance

Methods

addTagsToRoom()

addTagsToRoom(roomId: string | number, tags: string[]): Promise<object>;

Available in SDKMode.Manager; any other mode rejects with SDKErrorCode.ModeMismatch.

Adds the specified tags to a room.

Parameters

Parameter	Type	Description
`roomId`	`string` \| `number`	The room ID.
`tags`	`string`[]	Tag names to add.

Returns

Promise<object>

A promise that resolves with the result of the operation. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

await instance.addTagsToRoom('room-123', ['design', 'q1']);

Create a new tag with SDKInstance.createTag and apply it to a newly created room via SDKInstance.createRoom.

await instance.createTag('design');
const room = await instance.createRoom('Creative Hub', RoomType.Collaboration);
await instance.addTagsToRoom(room.id, ['design']);

createFile()

createFile(
   folderId: string | number, 
   title: string, 
   templateId?: string, 
   formId?: string
): Promise<TFileInfo>;

Available in SDKMode.Manager and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Creates a new file in the specified folder.

Parameters

Parameter	Type	Description
`folderId`	`string` \| `number`	The ID of the target folder.
`title`	`string`	The file title. An extension is optional: `"Report.docx"` keeps it, `"Report"` gets `.docx` from the portal.
`templateId`	`string`	The ID of a file to copy the content from. Omit for an empty document.
`formId`	`string`	The ID of a form to create the file from. Omit when the file is not based on a form.

Returns

Promise<TFileInfo>

A promise that resolves with TFileInfo. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const file = await instance.createFile('folder-123', 'Project Proposal');
console.log(file);

Create a file from a template and immediately open it in the editor using SDKInstance.setConfig.

const file = await instance.createFile('folder-123', 'Report.docx', 'template-456');
await instance.setConfig({ id: file.id, mode: SDKMode.Editor }, true);

createFolder()

createFolder(parentFolderId: string | number, title: string): Promise<TFolderInfo>;

Available in SDKMode.Manager and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Creates a new folder inside the specified parent folder.

Parameters

Parameter	Type	Description
`parentFolderId`	`string` \| `number`	The ID of the parent folder.
`title`	`string`	The folder title.

Returns

Promise<TFolderInfo>

A promise that resolves with TFolderInfo. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const folder = await instance.createFolder('parent-123', 'Archive');
console.log(folder);

Create a folder and immediately add a file inside it using SDKInstance.createFile.

const folder = await instance.createFolder('parent-123', 'Q1 Reports');
await instance.createFile(folder.id, 'Summary');

createHash()

createHash(password: string, hashSettings: object): Promise<object>;

Available in SDKMode.Manager and SDKMode.System; any other mode rejects with SDKErrorCode.ModeMismatch.

Creates a password hash using the provided hash settings.

Obtain hashSettings from SDKInstance.getHashSettings before calling this method.

Parameters

Parameter	Type	Description
`password`	`string`	The plaintext password to hash.
`hashSettings`	`object`	Hash algorithm settings from SDKInstance.getHashSettings.

Returns

Promise<object>

A promise that resolves with the generated hash. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const settings = await instance.getHashSettings();
const hash = await instance.createHash('p@ssw0rd', settings);
console.log(hash);

Full login flow using SDKInstance.getHashSettings and SDKInstance.login.

const settings = await instance.getHashSettings();
const hash = await instance.createHash('p@ssw0rd', settings);
await instance.login('user@example.com', hash, undefined, true);

createRoom()

createRoom(
   title: string, 
   roomType: string | number, 
   options?: TCreateRoomOptions
): Promise<TRoomInfo>;

Available in SDKMode.Manager; any other mode rejects with SDKErrorCode.ModeMismatch.

Creates a new room with the given type and optional settings.

note

The room type decides which access levels the room accepts: reviewing and commenting exist only in RoomType.Custom; a RoomType.Collaboration room offers editing and reading only. Creating a room requires the room admin role on the portal; a user without it gets a 403 result.

Parameters

Parameter	Type	Description
`title`	`string`	The room display name.
`roomType`	`string` \| `number`	The room type: a RoomType value or its numeric API value.
`options`	`TCreateRoomOptions`	Optional room settings. See TCreateRoomOptions. A JavaScript caller may still pass the positional arguments of SDK 2.1 (`quota`, `tags`, `color`, `cover`, `indexing`, `denyDownload`).

Returns

Promise<TRoomInfo>

A promise that resolves with TRoomInfo, or with { status, message } when the portal reports a failure — unlike the other methods, createRoom does not reject on portal errors.

Examples

const room = await instance.createRoom('Design Team', RoomType.Collaboration, { tags: ['design'] });
console.log(room);

Create a room, then create a new tag and apply it using SDKInstance.createTag and SDKInstance.addTagsToRoom.

const room = await instance.createRoom('Marketing', RoomType.Custom);
await instance.createTag('campaigns');
await instance.addTagsToRoom(room.id, ['campaigns']);

createTag()

createTag(name: string): Promise<object>;

Available in SDKMode.Manager; any other mode rejects with SDKErrorCode.ModeMismatch.

Creates a new tag with the given name.

Parameters

Parameter	Type	Description
`name`	`string`	The tag name.

Returns

Promise<object>

A promise that resolves with the created tag data. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const tag = await instance.createTag('Project Alpha');
console.log(tag);

Create a tag and immediately apply it to a room using SDKInstance.addTagsToRoom.

await instance.createTag('archived');
await instance.addTagsToRoom('room-123', ['archived']);

destroyFrame()

destroyFrame(): void;

Tears down the iframe and releases all resources associated with this instance.

Replaces the container with a plain <div> (preserving the original frameId and CSS classes, showing TFrameConfig.destroyText), removes the message listener, rejects pending method calls with SDKErrorCode.Disconnected, cancels the proactive OAuth token refresh, and removes the instance from the global DocSpace.SDK.frames registry (the frames map of the SDK that created it keeps the entry, so a later init* with the same frameId reuses the instance). In OAuth mode this is how a host ends the embedded session: no cookie exists, so nothing outlives the frame.

The call is synchronous and complete when it returns: the placeholder keeps the frameId, so an SDK.init* call on the same frameId may follow immediately — there is nothing to await.

Returns

void

Examples

instance.destroyFrame();

Destroy and reinitialize the same frame in a different mode using SDK.initEditor.

instance.destroyFrame();
sdk.initEditor({ frameId: 'ds-frame', src: 'https://portal.example.com', id: 99 });

executeInEditor()

executeInEditor(callback: (editor: any, asc: any, data?: any) => void, data?: object): Promise<object>;

Available in SDKMode.Editor and SDKMode.Viewer; in any other mode the portal answers that the method does not exist and the promise rejects with SDKErrorCode.ModeMismatch.

Runs a callback function inside the active document editor.

The callback is serialized with Function.prototype.toString and re-created inside the editor frame, so it must not reference outer-scope variables, closures or imports — pass everything it needs through data. The editor frame invokes it as callback(editor, asc, data):

editor — the DocsAPI editor object (window.DocEditor.instances[...]). Call editor.createConnector() yourself to get a connector with callCommand / executeMethod; the SDK does not create one for you.
asc — window.Asc of the editor frame. asc.scope is serialized into every connector.callCommand(fn) and is the way to pass data into Document Builder code.
data — the data argument of this method, JSON-serialized.

Parameters

Parameter	Type	Description
`callback`	(`editor`: `any`, `asc`: `any`, `data?`: `any`) => `void`	The function to run inside the editor context. Invoked as `callback(editor, asc, data)` — note that `data` is the third argument.
`data`	`object`	Optional JSON-serializable data passed as the third argument to `callback`.

Returns

Promise<object>

A promise that resolves with {} once the editor frame has run the callback. An error thrown by the callback is logged inside the editor frame and does not reject the promise.

Examples

instance.executeInEditor((editor, _asc, data) => {
  editor.insertText(data.text);
}, { text: 'Hello, World!' });

Initialize editor mode with SDK.initEditor and inject content when the document is ready.

const instance = sdk.initEditor({
  frameId: 'ds-editor',
  src: 'https://portal.example.com',
  id: 42,
  events: {
    onEditorOpen: () => {
      instance.executeInEditor((editor, _asc, data) => {
        editor.insertText(data.header);
      }, { header: 'Generated by SDK' });
    },
  },
});

Fill form fields with the Document Builder API through a connector. Data reaches the callCommand function via Asc.scope; the function itself must be closure-free.

instance.executeInEditor(function (editor, asc, data) {
  const connector = editor.createConnector();
  asc.scope = { values: data.values };
  connector.callCommand(function () {
    const doc = Api.GetDocument();
    for (const form of doc.GetAllForms()) {
      const value = Asc.scope.values[form.GetFormKey()];
      if (value === undefined) continue;
      if (form.GetFormType() === 'checkBoxForm') form.SetChecked(!!value);
      else form.SetText(String(value));
    }
  });
}, { values: { FullName: 'Jane Doe', Agree: true } });

getConfig()

getConfig(): TFrameConfig;

Returns the current merged configuration object.

Returns

TFrameConfig

The active TFrameConfig for this instance.

Examples

const config = instance.getConfig();
console.log(config.mode, config.src);

Preserve existing settings when making a partial update via SDKInstance.setConfig.

const config = instance.getConfig();
await instance.setConfig({ ...config, theme: Theme.Dark });

getFiles()

getFiles(): Promise<TFilesResponse>;

Available in SDKMode.Manager, SDKMode.Personal and SDKMode.Forms; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns the files in the folder currently open in the frame.

Returns

Promise<TFilesResponse>

A promise that resolves with TFilesResponse. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const files = await instance.getFiles();
console.log(files);

Open the first file in viewer mode via SDKInstance.setConfig.

const files = await instance.getFiles();
if (files.files[0]) {
  await instance.setConfig({ id: files.files[0].id, mode: SDKMode.Viewer }, true);
}

getFolderInfo()

getFolderInfo(): Promise<TFolderInfo>;

Available in SDKMode.Manager and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns metadata about the folder currently open in the frame.

Returns

Promise<TFolderInfo>

A promise that resolves with TFolderInfo. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const info = await instance.getFolderInfo();
console.log(info);

Check write access before calling SDKInstance.createFolder.

const info = await instance.getFolderInfo();
if (info.security?.create) {
  await instance.createFolder(info.id, 'Archive');
}

getFolders()

getFolders(): Promise<TFilesResponse>;

Available in SDKMode.Manager, SDKMode.Personal and SDKMode.Forms; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns the subfolders of the folder currently open in the frame.

Returns

Promise<TFilesResponse>

A promise that resolves with TFilesResponse. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const folders = await instance.getFolders();
console.log(folders);

Navigate into the first subfolder via SDKInstance.setConfig.

const folders = await instance.getFolders();
if (folders.folders[0]) {
  await instance.setConfig({ id: folders.folders[0].id }, true);
}

getHashSettings()

getHashSettings(): Promise<THashSettings>;

Available in SDKMode.Manager and SDKMode.System; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns the server's password hash settings needed by SDKInstance.createHash.

Returns

Promise<THashSettings>

A promise that resolves with THashSettings. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const settings = await instance.getHashSettings();
console.log(settings);

Full authentication flow using SDKInstance.createHash and SDKInstance.login.

const settings = await instance.getHashSettings();
const hash = await instance.createHash('p@ssw0rd', settings);
await instance.login('user@example.com', hash);

getList()

getList(): Promise<TFilesResponse>;

Available in SDKMode.Manager, SDKMode.Personal and SDKMode.Forms; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns all files and folders in the folder currently open in the frame.

Use SDKInstance.getFiles or SDKInstance.getFolders when you need only one content type.

Returns

Promise<TFilesResponse>

A promise that resolves with TFilesResponse. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const list = await instance.getList();
console.log(list);

const list = await instance.getList();
console.log('Files:', list.files.length, 'Folders:', list.folders.length);

getRooms()

getRooms(filter: TFrameFilter): Promise<TRoomsResponse>;

Available in SDKMode.Manager; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns a list of rooms, filtered by filter.

Parameters

Parameter	Type	Description
`filter`	`TFrameFilter`	Filter and sort criteria. See TFrameFilter.

Returns

Promise<TRoomsResponse>

A promise that resolves with TRoomsResponse. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const rooms = await instance.getRooms({
  search: 'alpha',
  sortBy: FilterSortBy.Name,
  sortOrder: FilterSortOrder.Ascending,
});
console.log(rooms);

Find rooms and remove an outdated tag from each using SDKInstance.removeTagsFromRoom.

const rooms = await instance.getRooms({ search: 'sprint-22' });
for (const room of rooms.folders) {
  await instance.removeTagsFromRoom(room.id, ['in-progress']);
}

The rooms of one room group (TFrameFilter.groupId), e.g. the rooms attached to a deal.

const deal = await instance.getRooms({ groupId: '42' });
console.log(deal.folders.map((room) => room.title));

getSelection()

getSelection(): Promise<TFileInfo[]>;

Available in SDKMode.Manager and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns the items currently selected in the frame.

Returns

Promise<TFileInfo[]>

A promise that resolves with an array of TFileInfo. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const selection = await instance.getSelection();
console.log(selection);

Pass the selection as context to SDKInstance.openModal.

const selection = await instance.getSelection();
if (selection.length > 0) {
  await instance.openModal('share', { items: selection });
}

getUserInfo()

getUserInfo(): Promise<TUserInfo>;

Available in SDKMode.Manager, SDKMode.System, SDKMode.Personal and SDKMode.Forms; any other mode rejects with SDKErrorCode.ModeMismatch.

Returns information about the currently authenticated user.

Returns

Promise<TUserInfo>

A promise that resolves with TUserInfo. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const user = await instance.getUserInfo();
console.log(user);

Apply the user's preferred locale via SDKInstance.setConfig.

const user = await instance.getUserInfo();
if (user.cultureName) {
  await instance.setConfig({ locale: user.cultureName });
}

initFrame()

initFrame(config: TFrameConfig): HTMLIFrameElement | null;

Inserts the ONLYOFFICE Apps iframe into the DOM element identified by TFrameConfig.frameId.

Merges config with defaultConfig and the instance's stored config, replaces the target <div> with a container holding the iframe (and an optional loader), attaches the message listener, and registers the instance in the global DocSpace.SDK.frames registry.

Called automatically by SDK.init. Call again to reinitialize in-place.

Parameters

Parameter	Type	Description
`config`	`TFrameConfig`	Frame configuration. See TFrameConfig.

Returns

HTMLIFrameElement | null

The created <iframe> element, or null if the target element was not found.

Examples

const iframe = instance.initFrame({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  mode: SDKMode.Viewer,
  id: 42,
});

With event handlers — see TFrameEvents for the full list of available events.

const iframe = instance.initFrame({
  frameId: 'ds-editor',
  src: 'https://portal.example.com',
  mode: SDKMode.Editor,
  id: 42,
  events: {
    onAppReady: () => console.log('ready'),
    onEditorOpen: () => console.log('document opened'),
    onEditorCloseCallback: () => history.back(),
  },
});

login(
   email: string, 
   passwordHash: string, 
   password?: string, 
   session?: boolean, 
   code?: string
): Promise<TLoginResult>;

Available in SDKMode.Manager and SDKMode.System; any other mode rejects with SDKErrorCode.ModeMismatch.

Authenticates a user using email and a hashed password.

Obtain passwordHash from SDKInstance.createHash. The portal's SDK dispatcher (client 4.0.0) forwards only email and passwordHash to its sign-in and always requests a persistent session; the REST endpoint behind it would also take a plaintext password and a session flag, but neither reaches it from the frame.

note

A failed sign-in is resolved, not rejected — see TLoginResult. url === "/" means a session exists; a url under /confirm/ means the account needs a second factor and no session was created — call login again with the same credentials and the one-time code; a status (401 for wrong credentials) with a message means the attempt failed. Only SDK-side failures reject: SDKErrorCode.Timeout, SDKErrorCode.Disconnected, SDKErrorCode.ModeMismatch — the latter also in OAuth mode (TFrameConfig.getToken or TFrameConfig.accessToken set), where the host owns the session and no cookie sign-in is possible. A portal whose SDK dispatcher predates the code argument ignores it and answers the challenge again; on such a portal the login page remains the only way to complete a two-factor sign-in.

Parameters

Parameter	Type	Description
`email`	`string`	The user's email address.
`passwordHash`	`string`	The hashed password (from SDKInstance.createHash).
`password`	`string`	Not forwarded by the portal's SDK dispatcher (client 4.0.0); use `passwordHash`.
`session`	`boolean`	Not forwarded by the portal's SDK dispatcher (client 4.0.0); the session is always persistent.
`code`	`string`	One-time code from the authenticator app or SMS; finishes a login that answered with a `/confirm/…` url.

Returns

Promise<TLoginResult>

A promise that resolves with the authentication result — see TLoginResult. Unlike the other methods, a portal failure is resolved as { status, message }, not rejected.

Examples

const result = await instance.login('user@example.com', passwordHash);
if (!result.url) throw new Error(result.message ?? 'login failed');

Two-factor sign-in using SDKInstance.getHashSettings and SDKInstance.createHash.

const settings = await instance.getHashSettings();
const hash = await instance.createHash('p@ssw0rd', settings);
const first = await instance.login('user@example.com', hash);
if (first.url?.startsWith('/confirm/')) {
  const code = await askUserForCode();
  const second = await instance.login('user@example.com', hash, undefined, undefined, code);
  if (second.status) throw new Error('wrong code');
}

logout()

logout(): Promise<object>;

Available in SDKMode.Manager and SDKMode.System; any other mode rejects with SDKErrorCode.ModeMismatch.

Ends the current user session.

In OAuth mode (TFrameConfig.getToken or TFrameConfig.accessToken set) there is no portal session to end: the frame authenticates every request with the host's token. The call rejects with SDKErrorCode.ModeMismatch; revoke the token on the host and call SDKInstance.destroyFrame instead.

Returns

Promise<object>

A promise that resolves with the logout result. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure, and with SDKErrorCode.ModeMismatch in OAuth mode.

Examples

await instance.logout();

Log out and immediately authenticate as a different user using SDKInstance.getHashSettings, SDKInstance.createHash, and SDKInstance.login.

await instance.logout();
const settings = await instance.getHashSettings();
const hash = await instance.createHash('newpassword', settings);
await instance.login('other@example.com', hash);

navigateSection()

navigateSection(section: 
  | "my-forms"
  | "in-progress"
  | "completed-forms"
  | "library"
  | "settings"
  | "my-documents"
  | "favorites"
  | "recent"
  | "shared-with-me"
| "trash"): Promise<object>;

Available in SDKMode.Forms and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Navigates the frame to a specific section.

Parameters

Parameter	Type	Description
`section`	\| `"my-forms"` \| `"in-progress"` \| `"completed-forms"` \| `"library"` \| `"settings"` \| `"my-documents"` \| `"favorites"` \| `"recent"` \| `"shared-with-me"` \| `"trash"`	Target section. For SDKMode.Forms — TFormsSection; for SDKMode.Personal — TPersonalSection.

Returns

Promise<object>

A promise that resolves when the navigation is complete. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure, or with SDKErrorCode.ModeMismatch in any other mode.

Examples

Forms mode.

await instance.navigateSection("completed-forms");

Personal mode.

const personal = sdk.initPersonal({
  frameId: 'ds-personal',
  src: 'https://portal.example.com',
});
await personal.navigateSection("trash");

openModal()

openModal(type: string, options: object): Promise<object>;

Available in SDKMode.Manager and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Opens a modal dialog of the specified type inside the frame.

Parameters

Parameter	Type	Description
`type`	`string`	The modal type identifier.
`options`	`object`	Modal-specific configuration options.

Returns

Promise<object>

A promise that resolves with the modal result. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

const result = await instance.openModal('invite', { roomId: 42 });
console.log(result);

Open a share dialog for the items currently selected in the frame using SDKInstance.getSelection.

const selection = await instance.getSelection();
if (selection.length > 0) {
  await instance.openModal('share', { items: selection });
}

removeTagsFromRoom()

removeTagsFromRoom(roomId: string | number, tags: string[]): Promise<object>;

Available in SDKMode.Manager; any other mode rejects with SDKErrorCode.ModeMismatch.

Removes the specified tags from a room.

Parameters

Parameter	Type	Description
`roomId`	`string` \| `number`	The room ID.
`tags`	`string`[]	Tag names to remove.

Returns

Promise<object>

A promise that resolves with the result of the operation. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

await instance.removeTagsFromRoom('room-123', ['draft', 'in-progress']);

Find rooms by name and clean up a tag from each using SDKInstance.getRooms.

const rooms = await instance.getRooms({ search: 'sprint-22' });
for (const room of rooms.folders) {
  await instance.removeTagsFromRoom(room.id, ['in-progress']);
}

setConfig()

setConfig(config?: Partial<TFrameConfig>, reload?: boolean): Promise<object>;

Merges config into the stored config and sends it to the iframe.

When reload is true, reinitializes the iframe entirely via SDKInstance.initFrame instead of sending a postMessage update.

Parameters

Parameter	Type	Default value	Description
`config`	`Partial`<`TFrameConfig`>	`{}`	Partial frame configuration to merge into the stored config.
`reload`	`boolean`	`false`	When `true`, reinitializes the frame. Defaults to `false`.

Returns

Promise<object>

A promise that resolves with the iframe's response, or with the merged config if reload is true. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

await instance.setConfig({ theme: Theme.Dark, locale: 'fr-FR' });

Switch to a different document while keeping existing settings — read them first via SDKInstance.getConfig.

const current = instance.getConfig();
await instance.setConfig({ ...current, id: 99, mode: SDKMode.Editor }, true);

setCustomActions()

setCustomActions(config: TCustomActionsConfig): Promise<object>;

Replaces the custom actions of the frame: context menu items for files, folders and rooms and items of the create ("+") menu. Groups left out of config are cleared; pass {} to remove all items. Available in SDKMode.Manager, SDKMode.Personal and SDKMode.Forms. Room actions are shown in SDKMode.Manager only, create menu items in SDKMode.Manager and SDKMode.Personal. When an action is clicked, TFrameEvents.onCustomAction fires with a TCustomActionEvent. To show the items from the first render, set TFrameConfig.customActions instead.

Parameters

Parameter	Type	Description
`config`	`TCustomActionsConfig`	Custom actions configuration. See TCustomActionsConfig.

Returns

Promise<object>

A promise that resolves when the actions are applied. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure, or with SDKErrorCode.ModeMismatch in any other mode.

Examples

await instance.setCustomActions({
  contextMenu: {
    file: [
      { key: "send-to-crm", label: "Send to CRM", icon: "https://example.com/icon.svg" },
      { key: "export", label: "Export", extensions: ["pdf"] },
    ],
    room: [{ key: "unlink", label: "Unlink from deal", requireSecurity: ["EditRoom"] }],
  },
  createMenu: [{ key: "upload-from-crm", label: "Upload from CRM" }],
});

Handle the custom action event on the host page.

const manager = sdk.initManager({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  events: {
    onCustomAction: ({ action, items }) => console.log(action, items),
  },
});
await manager.setCustomActions({
  contextMenu: { file: [{ key: "approve", label: "Approve" }] },
});

setIsLoaded()

setIsLoaded(): void;

Marks the frame as loaded: fades out the loader spinner, reveals the iframe, and fires TFrameEvents.onContentReady.

The ONLYOFFICE Apps iframe calls this automatically once its content is ready, so most integrations never need to. Call it manually to reveal the frame on your own schedule, for example when the host page shows its own loading overlay. Every call re-applies the iframe size and visibility and fires TFrameEvents.onContentReady; the loader is removed by the first one.

Returns

void

Examples

instance.setIsLoaded();

Reveal the frame from a host-side button instead of waiting for the iframe, then react to the completion via TFrameEvents.onContentReady.

const instance = sdk.initManager({
  frameId: 'ds-frame',
  src: 'https://portal.example.com',
  events: { onContentReady: () => console.log('Frame is visible') },
});

document.getElementById('show-frame').onclick = () => instance.setIsLoaded();

setListView()

setListView(viewType: "row" | "table" | "tile"): Promise<object>;

Available in SDKMode.Manager and SDKMode.Personal; any other mode rejects with SDKErrorCode.ModeMismatch.

Switches the file list display mode.

Parameters

Parameter	Type	Description
`viewType`	`"row"` \| `"table"` \| `"tile"`	The view mode: `"row"`, `"table"`, or `"tile"`.

Returns

Promise<object>

A promise that resolves with the result of the operation. Rejects with SDKError (SDKErrorCode.ApiError) when the portal reports a failure.

Examples

await instance.setListView('table');

Switch to tile view only when in manager mode — read the current mode via SDKInstance.getConfig.

const { mode } = instance.getConfig();
if (mode === SDKMode.Manager) {
  await instance.setListView('tile');
}

upload()

upload(file: File): Promise<object>;

Uploads a file into the frame's current location: the form filling room in SDKMode.Forms, the open folder in SDKMode.Personal. The file is transferred to the iframe via zero-copy ArrayBuffer and uploaded using the chunked upload API. The file list refreshes automatically when complete.

Parameters

Parameter	Type	Description
`file`	`File`	The file to upload. Callers should validate type and size before calling.

Returns

Promise<object>

A promise that resolves with the TUploadResult of TFrameEvents.onUploadSuccess, so a handler for that event is optional. Rejects with SDKErrorCode.UploadFailed on TFrameEvents.onUploadError or after 120 seconds, SDKErrorCode.ModeMismatch in any other mode, SDKErrorCode.Disconnected before the frame is connected.

note

The entire file is read into memory via arrayBuffer() before transfer. Callers should validate file size before invoking this method to avoid excessive memory usage on the host page. The server-side upload limit is configured in ONLYOFFICE Apps and will reject files that exceed it.

The ArrayBuffer is transferred to the iframe (zero-copy). After upload() returns, the buffer is neutered and cannot be reused.

TFrameConfig.methodTimeout does not apply to the transfer, and TFrameEvents.onUploadProgress is not emitted for it.

Examples

const input = document.querySelector("input[type=file]");
const file = input.files[0];
const result = await instance.upload(file);

Upload with error handling.

try {
  await forms.upload(file);
  console.log("Upload complete");
} catch (err) {
  console.error("Upload failed:", err.message);
}

Properties

Property	Type	Description
`config`	`TFrameConfig`	The iframe configuration options. See TFrameConfig.

Example​

Constructors​

Constructor​

Parameters​

Returns​

Methods​

addTagsToRoom()​

Parameters​

Returns​

Examples​

createFile()​

Parameters​

Returns​

Examples​

createFolder()​

Parameters​

Returns​

Examples​

createHash()​

Parameters​

Returns​

Examples​

createRoom()​

Parameters​

Returns​

Examples​

createTag()​

Parameters​

Returns​

Examples​

destroyFrame()​

Returns​

Examples​

executeInEditor()​

Parameters​

Returns​

Examples​

getConfig()​

Returns​

Examples​

getFiles()​

Returns​

Examples​

getFolderInfo()​

Returns​

Examples​

getFolders()​

Returns​

Examples​

getHashSettings()​

Returns​

Examples​

getList()​

Returns​

Examples​

getRooms()​

Parameters​

Returns​

Examples​

getSelection()​

Returns​

Examples​

getUserInfo()​

Returns​

Examples​

initFrame()​

Parameters​

Returns​

Examples​

login()​

Parameters​

Returns​

Examples​

logout()​

Returns​

Examples​

navigateSection()​

Parameters​

Returns​

Examples​

Example

Constructors

Constructor

Parameters

Returns

Methods

addTagsToRoom()

Parameters

Returns

Examples

createFile()

Parameters

Returns

Examples

createFolder()

Parameters

Returns

Examples

createHash()

Parameters

Returns

Examples

createRoom()

Parameters

Returns

Examples

createTag()

Parameters

Returns

Examples

destroyFrame()

Returns

Examples

executeInEditor()

Parameters

Returns

Examples

getConfig()

Returns

Examples

getFiles()

Returns

Examples

getFolderInfo()

Returns

Examples

getFolders()

Returns

Examples

getHashSettings()

Returns

Examples

getList()

Returns

Examples

getRooms()

Parameters

Returns

Examples

getSelection()

Returns

Examples

getUserInfo()

Returns

Examples

initFrame()

Parameters

Returns

Examples

login()

Parameters

Returns

Examples

logout()

Returns

Examples

navigateSection()

Parameters

Returns

Examples