Skip to main content

Quickstart

note

Before you begin, make sure you meet the prerequisites.

There are two ways to embed a working ONLYOFFICE Apps instance in your web application. You can do it using an HTML script tag, or installing our npm package. Both methods render ONLYOFFICE Apps inside a div you control.

Embedding with a script tag​

The fastest way to get ONLYOFFICE Apps running in your app is via a script tag. No install required.

Step 1. Add a placeholder div to your HTML file:

<div id="ds-frame"></div>

Step 2. Load the SDK from your ONLYOFFICE Apps server:

<script src="https://your-docspace.onlyoffice.com/static/scripts/sdk/2.2.0/api.js"></script>

Step 3. Initialize the frame:

const docSpace = DocSpace.SDK.initManager({
  frameId: "ds-frame",
  src: "https://your-docspace.onlyoffice.com",
});

The ONLYOFFICE Apps instance will render inside the ds-frame div. Users who are already logged in will see their workspace immediately. Users who are not logged in will be prompted to sign in.

src must be the portal's own absolute URL — the SDK only accepts messages from the iframe if they come from that exact origin, so a src that redirects to a different origin on load will leave the frame looking stuck, with no error of its own.

Below is a basic working example you can save and serve to verify your setup:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>ONLYOFFICE Apps</title>
    <style>
      html,
      body {
        margin: 0;
        padding: 0;
        height: 100%;
      }
    </style>
  </head>
  <body>
    <div id="ds-frame"></div>

    <script src="https://your-docspace.onlyoffice.com/static/scripts/sdk/2.2.0/api.js"></script>

    <script>
      const config = {
        frameId: "ds-frame",
        src: "https://your-docspace.onlyoffice.com",
        height: "700px",
        showMenu: true, // optional
        // other configurations
      };

      const docSpace = DocSpace.SDK.initManager(config);
    </script>
  </body>
</html>

This example uses the initManager mode. Configuration options may change depending on the type of embedding mode. For a full breakdown, see Comparison of embedding modes.

tip

If you are testing on localhost, make sure to whitelist your local origin (e.g., http://localhost:<port>) in ONLYOFFICE Apps Developer Tools → Embed SDK.

Using the npm package​

The example below uses React and Vite, but the SDK works with any modern bundler. If you are using a different stack, the setup steps will differ, but the SDK initialization code stays the same. You will need Node.js installed.

Step 1. Create a new React + Vite project:

npm create vite@latest docspace-app -- --template react -y

Step 2. Install the dependencies and the SDK:

cd docspace-app
npm install
npm install @onlyoffice/docspace-sdk-js

Step 3. Replace the contents of src/App.jsx with the following:

import { useEffect } from "react";
import SDK from "@onlyoffice/docspace-sdk-js";

export default function App() {
  useEffect(() => {
    const sdk = new SDK();

    const instance = sdk.initManager({
      frameId: "ds-frame",
      src: "https://your-docspace.onlyoffice.com",
      height: "700px",
      showMenu: true,
      // additional configuration options
    });

    return () => {
      instance.destroyFrame();
    };
  }, []);

  return <div id="ds-frame" />;
}

Step 4. Run the app:

npm run dev

Open http://localhost:5173 in your browser to access your ONLYOFFICE Apps instance.

tip

If you are testing on localhost, make sure to whitelist your local origin (e.g., http://localhost:5173) in ONLYOFFICE Apps Developer Tools → Embed SDK. If you still see a Content Security Policy (CSP) error, add checkCSP: false to your config (for local development only).

What's next​

Now that ONLYOFFICE Apps is running, a few parameters to explore:

  • showMenu — show or hide the left navigation panel
  • width / height — control the frame dimensions (percentages or pixels)
  • theme — set the UI theme
  • locale — set the interface language using a four-letter language code
  • events — attach callbacks for SDK lifecycle events

For the full list of available parameters, see TFrameConfig. For other initialization modes such as initEditor, initViewer, or initRoomSelector, see Embedding modes.