TFrameConfig

The main configuration object for initializing an ONLYOFFICE Apps frame. Passed to SDKInstance.initFrame or any SDK.init* wrapper.

Only frameId, mode, and src are required — all other fields have defaults from defaultConfig. The SDK.init* wrappers set mode themselves and take a TInitConfig, where only frameId and src are required.

type TFrameConfig = object;

Example

const config: TFrameConfig = {
  frameId: "ds-frame",
  src: "https://portal.example.com",
  mode: "manager",
  width: "100%",
  height: "700px",
  theme: "Dark",
};
sdk.init(config);

Properties

Property	Type	Description
acceptButtonLabel	string	Custom label for the selector "Accept" button.
acceptExtensions	string	Accepted file extensions for SDKMode.Uploader (e.g. ".pdf,.docx").
accessToken	string	Static OAuth access token (convenience). The SDK wraps it as getToken: () => accessToken. The SDK cannot refresh it — prefer TFrameConfig.getToken for anything longer than the token TTL.
agentId	string | number	AI agent room ID. Optional in SDKMode.Chat: when set, the chat is bound to that agent; when omitted, the chat is bound to the current user. The chat renders its composer only for a signed-in user who is not a guest; otherwise the page shows a no-access state and fires TFrameEvents.onNoAccess. AI disabled on the portal also hides the composer, without the event.
buttonColor	string	HEX color for the selector accept button. Default: "#5299E0". Deprecated ONLYOFFICE Apps 4.0 does not read it; the selector uses the portal theme.
cancelButtonLabel	string	Custom label for the selector "Cancel" button.
checkCSP	boolean	Validate the host against the portal's CSP allowlist before loading the iframe (host name and port only). false skips the request to CSPApiUrl; the browser still enforces the portal's frame-ancestors header. Default: true.
customActions	TCustomActionsConfig	Custom items for the context menus and the create menu in SDKMode.Manager, SDKMode.Personal and SDKMode.Forms, applied when the frame loads. Clicks fire TFrameEvents.onCustomAction. Replace them later with SDKInstance.setCustomActions. Not available through the script-tag parameters. Unset by default.
destination	TFormsSection	Initial section to display in SDKMode.Forms. Determines which page loads when the frame is created, avoiding an extra SDKInstance.navigateSection call. See TFormsSection. Default: "my-forms".
destroyText	string	Plain text shown in the placeholder div after SDKInstance.destroyFrame. Markup is not rendered. Default: "".
disableActionButton	boolean	Hide the "Actions" button in SDKMode.Manager. Default: false.
downloadToEvent	boolean	Redirect download links to TFrameEvents.onDownload instead of downloading directly, in SDKMode.Manager, SDKMode.PublicRoom and SDKMode.Personal. Default: false.
editorCustomization	TEditorCustomization	Editor UI customization. See TEditorCustomization. Default: {}.
editorGoBack	boolean | "event"	The "Open file location" button of the editor. true = the button opens the file's folder; "event" = the button fires TFrameEvents.onEditorCloseCallback instead (set automatically when the handler is registered); false = no button. Default: true.
editorType	TEditorType	Editor UI layout sent to the backend. See EditorType. Default: "desktop".
emplType	string	Employee type for the sign-up through TFrameConfig.providerName in SDKMode.Forms, SDKMode.Chat and SDKMode.Personal.
entityId	string | number	ID of the room or folder the chat is opened from — the user's current location. Optional in SDKMode.Chat; undefined by default. The AI receives it as workspace context and by default scopes tool calls (searches, listings, folder contents) to this location. The current user must have access to the entity, otherwise chat requests are rejected.
events	TFrameEvents	Event handlers. See TFrameEvents.
extensionsText	string	File extensions hint text in SDKMode.Uploader.
fileId	string | number	File ID to attach to the chat composer on init. Optional in SDKMode.Chat.
filter	TFrameFilter	Filter/sort/pagination for the file list. See TFrameFilter.
filterParam	string	File type filter for SDKMode.FileSelector. "ALL" = no restriction. Default: "ALL".
frameId	string	Required. Unique frame identifier. Used as the DOM id and the postMessage routing key. Default: "ds-frame".
getToken	() => string | Promise<string>	OAuth access-token provider. Setting it (or TFrameConfig.accessToken) switches the frame into OAuth mode: the frame authorizes API calls with Authorization: Bearer <token> instead of the session cookie, so no cookie is set and the portal session cannot outlive a sign-out in the host application. The host backend runs the authorization-code and refresh-token exchange and returns a fresh access token; client_secret and refresh tokens never reach the browser. The SDK calls it at start, after a 401 and, for a JWT or with TFrameConfig.tokenExpiresAt, one minute before expiry. SDKInstance.login and SDKInstance.logout reject with SDKErrorCode.ModeMismatch in OAuth mode, and token failures surface through TFrameEvents.onAuthError. Default: undefined.
headerHeight	number	Height (in px) of the header component inside the iframe. When unset, ONLYOFFICE Apps uses its own built-in header height; supply this only to override it so the embedded UI matches the host application's chrome. Currently honored in SDKMode.Forms, SDKMode.Personal and SDKMode.Chat.
headerOffset	number	Inline-start padding (in px) added to header rows so host overlays on the left edge (e.g. Nextcloud floating menu) don't cover the burger / breadcrumbs / chat-header controls. The outer iframe container is not shifted — only the elements inside the header move to the right (or to the left in RTL). Currently honored in SDKMode.Forms, SDKMode.Personal and SDKMode.Chat. Default: 0.
height	string	Iframe height. CSS value: "100%", "600px", etc. Default: "100%".
id	string | number | null	Entity ID: the file in SDKMode.Editor and SDKMode.Viewer, the target folder in SDKMode.Uploader, the room in SDKMode.PublicRoom, the folder to open in SDKMode.Personal, the form filling room in SDKMode.Forms (optional there: the room from the portal's Forms settings is used when unset). Default: null.
infoPanelVisible	boolean	Show info panel toggle in SDKMode.Manager. Default: true.
init	boolean | null	Reserved. Controls whether the frame should auto-initialize.
integrationUrl	string	URL of the integration page. Deprecated ONLYOFFICE Apps 4.0 does not read it: the frame returns the user to its own origin after external navigation (e.g. billing).
inviteKey	string	Invitation key for the sign-up through TFrameConfig.providerName in SDKMode.Forms, SDKMode.Chat and SDKMode.Personal.
isFolderUpload	boolean	Allow folder upload in SDKMode.Uploader.
isMultipleUpload	boolean	Allow multiple file upload in SDKMode.Uploader.
libraryId	string	Library ID for SDKMode.Forms to display only items from a forms library.
linkMainText	string	Link main text in SDKMode.Uploader.
locale	string | null	UI locale as a BCP 47 code (e.g. "en-US"). Applies to the frame only. null = the language configured on the portal or in the signed-in user's profile. Default: null.
maxPerUploadSize	string	Max single file/folder size in SDKMode.Uploader.
maxTotalUploadSize	string	Max total upload size in SDKMode.Uploader.
methodTimeout	number	Timeout in milliseconds for method calls to the iframe. If the iframe does not respond within this time, the call rejects with SDKErrorCode.Timeout and TFrameEvents.onAppError fires. Does not apply to SDKInstance.upload, which has its own 120-second transfer timeout. Default: 30000 (30 seconds).
mode	TFrameMode	Required. SDK mode. Determines UI and available methods. See SDKMode.
name	string	Iframe name attribute prefix. Default: FRAME_NAME.
noLoader	boolean	Skip the loading spinner. true = iframe appears immediately. Forced per mode: SDKMode.Manager and SDKMode.System always show the spinner (false), SDKMode.Forms and SDKMode.Personal never do (true). Default: true.
openEditorInSameTab	boolean	Where a file opens from the list in SDKMode.Forms and SDKMode.Personal when TFrameEvents.onEditorOpen is not set: true navigates the host page to the editor, false opens a new tab. Unset = the portal's "Open in the same tab" setting.
personalDestination	TPersonalSection	Initial section to display in SDKMode.Personal. Determines which page loads when the frame is created, avoiding an extra SDKInstance.navigateSection call. See TPersonalSection. Default: "my-documents".
providerName	string	Third-party sign-in provider (e.g. "nextcloud") for automatic sign-in and sign-up in SDKMode.Forms, SDKMode.Chat and SDKMode.Personal: a visitor without a portal session is sent through that provider and returned to the frame. A cookie-based flow, unrelated to OAuth mode (TFrameConfig.getToken).
requestToken	string | null	Share key of an external link: the room link in SDKMode.PublicRoom and SDKMode.Manager, the file link in SDKMode.Editor and SDKMode.Viewer. Ignored by other modes. Obtain it from TRequestTokenInfo.requestToken. Default: null.
roomType	string	Room type filter for SDKMode.RoomSelector: a RoomType API value as a string ("5" for custom rooms).
rootPath	string	Base navigation path for SDKMode.Manager. Default: "/rooms/shared/".
secondaryText	string	Secondary description text in SDKMode.Uploader.
selectorType	TSelectorType	Content filter for selector modes. See SelectorFilterType. Default: "all".
showFilter	boolean	Show filter toolbar in SDKMode.Manager, with the create menu that holds TCustomActionsConfig.createMenu items. Default: false.
showHeader	boolean	Show the header bar in the mobile view of SDKMode.Manager. Not read by other modes. Default: false.
showHeaderBanner	TBannerDisplaying	Header banner visibility in SDKMode.Manager. See HeaderBannerDisplaying. Default: "none".
showMenu	boolean	Show the left navigation menu in SDKMode.Manager and SDKMode.Forms. Forms reads it when the frame loads, so a later SDKInstance.setConfig can hide the menu but not show it. SDKMode.Personal has no navigation menu: switch its sections with SDKInstance.navigateSection. Default: false.
showSelectorCancel	boolean	Show "Cancel" button in selector modes. Default: false.
showSelectorHeader	boolean	Show header bar in selector modes. Default: false.
showSettings	boolean	Show "Manage displayed columns" button in table view. Default: false.
showSignOut	boolean	Show "Sign out" button. Default: true.
showTitle	boolean	Show current section/room/folder title in SDKMode.Manager. Default: true.
src	string	Required. ONLYOFFICE Apps portal URL. Used as the iframe src origin.
stylesUrl	string	Absolute http/https URL of a stylesheet applied inside the frame, in every mode. A relative or non-HTTP URL is dropped silently. The portal loads it cross-origin, so the serving host must allow it with CORS.
theme	TTheme	Color theme. See Theme. Default: "System".
threadId	string	Thread ID to resume. Optional in SDKMode.Chat.
tokenExpiresAt	number	Expiry of the first access token as epoch milliseconds, for the proactive refresh in OAuth mode. When omitted, the expiry is read from the token's JWT exp claim. Tokens obtained by a refresh always use their own exp claim; an opaque token without one is refreshed on demand only, after a 401.
type	TEditorType	Platform layout. Affects iframe CSS (e.g. "mobile" sets position: fixed). See EditorType. Default: "desktop".
uid	string	User identifier passed to the sign-in through TFrameConfig.providerName in SDKMode.Forms, SDKMode.Chat and SDKMode.Personal.
viewAs	TManagerViewMode	Item layout in SDKMode.Manager. See ManagerViewMode. Default: "row". Deprecated ONLYOFFICE Apps 4.0 does not read it: the layout is the one the user last chose. Call SDKInstance.setListView after TFrameEvents.onAppReady instead.
viewTableColumns	string	Visible table columns in SDKMode.Manager, comma-separated. Applies in the table layout only (SDKInstance.setListView); a column set the user saved in the browser takes precedence. Default: "Index,Name,Size,Type,Tags".
waiting	boolean	Delay iframe append. When true, the iframe is not rendered until SDKInstance.setConfig is called with reload = true (without reload the call rejects with SDKErrorCode.Disconnected). SDKMode.System ignores the flag. Default: false.
width	string	Iframe width. CSS value: "100%", "800px", etc. Default: "100%".
withBreadCrumbs	boolean	Show breadcrumb navigation in selector modes. Default: true.
withSearch	boolean	Show search bar in selector modes. Default: true.
withSubtitle	boolean	Show the subtitle with the folder description in SDKMode.FileSelector. Not passed to SDKMode.RoomSelector. Default: true.