🎉 v0.5.1 is released. Read more →
GuidesUniver SheetsGet StartedInstallation & Basic Usage

Installation & Basic Usage

Univer is designed with a plugin system, we provide a rich set of plugins to help you build your own electronic document application more flexibly. You can selectively manually combine and import these plugins according to your own needs.

Since version 0.5.0, Univer provides the @univerjs/presets package, which can help you quickly build a Univer application without having to worry about the plugin design and how to import and configure those cumbersome plugins. Therefore, if you are a first-time developer using Univer, we recommend starting with Presets.

⚠️

It should be noted that whether you use the Presets package or manually combine the installation, you must ensure that all preset or plugin versions are consistent.

This chapter will guide you on how to build a basic Univer Sheets application using the Univer Presets package or by piecemeal installation.

Using with Presets

Univer Presets provides a series of plugin combinations based on the functional scenarios of electronic documents, so that you can quickly build a Univer application. A preset typically includes plugins, style files, language packs, Facade API, etc.

Here we will briefly introduce how to quickly build a Univer Sheets application with less than twenty lines of code.

Using with Package Manager

If you have already introduced modern front-end development tools into your project, introducing Univer will be very simple. We recommend using Vite, esbuild, or Webpack 5 and other build tools that support ES Module well to build Univer applications. If you are using other build tools (such as Webpack 4), you may need some additional configuration, please read Troubleshooting for more information.

Installation

Choose your package manager to install @unvierjs/presets:

npm install @univerjs/presets

Usage

With the following code, you can start an Univer Sheets application:

import { createUniver, defaultTheme, LocaleType, Tools } from '@univerjs/presets';
import { UniverSheetsCorePreset } from '@univerjs/presets/preset-sheets-core';
import UniverPresetSheetsCoreEnUS from '@univerjs/presets/preset-sheets-core/locales/en-US';
 
import '@univerjs/presets/lib/styles/preset-sheets-core.css';
 
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    enUS: UniverPresetSheetsCoreEnUS,
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
});
 
univerAPI.createUniverSheet({ name: 'Test Sheet' });
createUniver Method

The createUniver method accepts a configuration object that contains the configuration information of Univer, such as language, theme, plugins, etc. This method returns an object containing the Univer instance and Univer Facade API instance.

The properties of the configuration object are as follows:

  • locale: Language environment, can be an LocaleType enumeration value.
  • locales: Locales, an object, the key is the language environment, and the value is the language pack object.
  • theme: Theme, a theme object.
  • presets: An array of presets that contains the presets to be registered, such as UniverSheetsCorePreset.
  • plugins: An array of plugins that contains the plugins that need to be registered additionally.

When you use a plugin that is not included in any preset package or you have implemented a plugin yourself, you can register these plugins through the plugins property. You can also choose to register plugins by calling the univer.registerPlugin method after obtaining the Univer instance.

Using with <script> Tag

If you are not using a package manager, you can also include Univer via the <script> tag.

We provide UMD builds of Univer on popular CDN services (such as jsDelivr, unpkg), you can include these resources in your HTML file (of course, you can also download these files and distribute them through your own server or CDN network):

Example

<head>
  <script src="https://unpkg.com/react/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
  <script src="https://unpkg.com/rxjs/dist/bundles/rxjs.umd.min.js"></script>
 
  <script src="https://unpkg.com/@univerjs/presets/lib/umd/index.js"></script>
  
  <script src="https://unpkg.com/@univerjs/preset-sheets-core/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/preset-sheets-core/lib/umd/locales/en-US.js"></script>
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/preset-sheets-core/lib/index.css" />
  <style>
    html,
    body,
    #root,
    #app {
      padding: 0;
      margin: 0;
      height: 100%;
    }
  </style>
</head>
<body>
  <div id="app"></div>
 
  <script>
    const { createUniver, LocaleType, Tools, defaultTheme } = UniverPresets
    const { UniverSheetsCorePreset } = UniverPresetSheetsCore
 
    const { univerAPI } = createUniver({
      locale: LocaleType.EN_US,
      locales: {
        enUS: Tools.deepMerge(
          {},
          UniverPresetSheetsCoreEnUS,
        ),
      },
      theme: defaultTheme,
      presets: [
        UniverSheetsCorePreset(),
      ],
    });
 
    univerAPI.createUniverSheet({ name: 'Test Sheet' }); // Create your first sheet named 'Test Sheet'
  </script>
</body>

univerAPI is the API object that you can use to interact with Univer.

Specifying Versions

Both unpkg and jsDeliver support specifying resources of specific versions. For example, if you want to use version 0.5.0 of Univer, you only need to add @<version> to the URL to specify the version:

- https://unpkg.com/@univerjs/presets/lib/umd/index.js
+ https://unpkg.com/@univerjs/presets@0.5.0/lib/umd/index.js

Piecemeal Installation

When you need to more flexibly control when the plugins are loaded, or want to more finely import plugins on demand, you can choose to piecemeal installation of plugins. Here we only take the most basic Univer Sheets application as an example to introduce how to install plugins by piecemeal installation.

Unlike Presets, piecemeal installation of plugins does not include Facade API by default. The parts related to Facade API in the following code examples are optional, and you can decide whether to delete them according to your needs.

Using with Package Manager

Installation

Univer uses React to develop views (of course, this does not affect your use of Univer in Vue or Angular), and uses Rxjs to process data streams. Since these two libraries are widely used in modern front-end development, we list them as peerDependencies. Different package management tools have different behaviors for peerDependencies, so you may need to pay attention to some details.

💡
  • If you are using npm, make sure you are using npm@7 or higher. This is because npm@3 ~ npm@6 will not correctly install peerDependencies1.
  • If you are using pnpm, make sure you are using pnpm@8 or higher. If you are using pnpm@6 ~ pnpm@7, you can try configuring auto-install-peers=true 2 to resolve dependency installation issues.
  • If you are using yarn, you need to manually install the missing peerDependencies3, but don’t worry, the installation commands below already include these dependencies.
npm install @univerjs/core @univerjs/design @univerjs/docs @univerjs/docs-ui @univerjs/engine-formula @univerjs/engine-render @univerjs/sheets @univerjs/sheets-formula @univerjs/sheets-formula-ui @univerjs/sheets-numfmt @univerjs/sheets-numfmt-ui @univerjs/sheets-ui @univerjs/ui

Usage

💡

The order of importing style files is very important. Make sure you import the CSS styles of @univerjs/design and @univerjs/ui before importing the style files of other plugins.

You need to import Univer’s style files, language packs, and some necessary plugins in your project:

import { LocaleType, Tools, Univer, UniverInstanceType, FUniver } from "@univerjs/core";
import { defaultTheme } from "@univerjs/design";
 
import { UniverFormulaEnginePlugin } from "@univerjs/engine-formula";
import { UniverRenderEnginePlugin } from "@univerjs/engine-render";
import { UniverUIPlugin } from "@univerjs/ui";
import { UniverDocsPlugin } from "@univerjs/docs";
import { UniverDocsUIPlugin } from "@univerjs/docs-ui";
import { UniverSheetsPlugin } from "@univerjs/sheets";
import { UniverSheetsUIPlugin } from "@univerjs/sheets-ui";
import { UniverSheetsFormulaPlugin } from "@univerjs/sheets-formula";
import { UniverSheetsFormulaUIPlugin } from "@univerjs/sheets-formula-ui";
import { UniverSheetsNumfmtPlugin } from "@univerjs/sheets-numfmt";
import { UniverSheetsNumfmtUIPlugin } from "@univerjs/sheets-numfmt-ui";
 
import DesignEnUS from '@univerjs/design/locale/en-US';
import UIEnUS from '@univerjs/ui/locale/en-US';
import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US';
import SheetsEnUS from '@univerjs/sheets/locale/en-US';
import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US';
import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US';
import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US';
 
// The Facade API here is optional, you can decide whether to import it according to your needs
import '@univerjs/engine-formula/facade';
import '@univerjs/ui/facade';
import '@univerjs/docs-ui/facade';
import '@univerjs/sheets/facade';
import '@univerjs/sheets-ui/facade';
import '@univerjs/sheets-formula/facade';
import '@univerjs/sheets-numfmt/facade';
 
import "@univerjs/design/lib/index.css";
import "@univerjs/ui/lib/index.css";
import "@univerjs/docs-ui/lib/index.css";
import "@univerjs/sheets-ui/lib/index.css";
import "@univerjs/sheets-formula-ui/lib/index.css";

Then create a Univer instance and register these plugins:

const univer = new Univer({
  theme: defaultTheme,
  locale: LocaleType.EN_US,
  locales: {
    [LocaleType.EN_US]: Tools.deepMerge(
      SheetsEnUS,
      DocsUIEnUS,
      SheetsUIEnUS,
      SheetsFormulaUIEnUS,
      UIEnUS,
      DesignEnUS,
    ),
  },
});
 
univer.registerPlugin(UniverRenderEnginePlugin);
univer.registerPlugin(UniverFormulaEnginePlugin);
 
univer.registerPlugin(UniverUIPlugin, {
  container: 'app',
});
 
univer.registerPlugin(UniverDocsPlugin);
univer.registerPlugin(UniverDocsUIPlugin);
 
univer.registerPlugin(UniverSheetsPlugin);
univer.registerPlugin(UniverSheetsUIPlugin);
univer.registerPlugin(UniverSheetsFormulaPlugin);
univer.registerPlugin(UniverSheetsFormulaUIPlugin);
 
univer.createUnit(UniverInstanceType.UNIVER_SHEET, {});
 
const univerAPI = FUniver.newAPI(univer);

Lazy Loading Plugins

One advantage of using the piecemeal installation method is that you can more flexibly control when the plugins are loaded. A common way is to load only the necessary plugins when the application is initialized, and delay the loading of some plugins until after the first rendering is completed.

Univer’s [official demo]((https://github.com/dream-num/univer/blob/dev/examples/src/sheets/main.ts) uses this optimization technique for reference.

Using with <script> Tag

Like Presets, Univer also provides UMD packages for each plugin, but unlike Presets, you need to manually import the UMD packages for each plugin. This process is very cumbersome, and we do not recommend this method. Please consider using it only after fully understanding the plugin mechanism (such as the dependencies between plugins and the order of importing plugin style files).

Example

<head>
  <script src="https://unpkg.com/react/umd/react.production.min.js"></script>
  <script src="https://unpkg.com/react-dom/umd/react-dom.production.min.js"></script>
  <script src="https://unpkg.com/rxjs/dist/bundles/rxjs.umd.min.js"></script>
 
  <script src="https://unpkg.com/@univerjs/protocol/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/core/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/telemetry/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/rpc/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/design/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/engine-render/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/engine-numfmt/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/engine-formula/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/drawing/lib/umd/index.js"></script>
 
  <script src="https://unpkg.com/@univerjs/ui/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/docs/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/docs-ui/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-ui/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-formula/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-formula-ui/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-numfmt/lib/umd/index.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-numfmt-ui/lib/umd/index.js"></script>
 
  <script src="https://unpkg.com/@univerjs/engine-formula/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/ui/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/docs-ui/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-ui/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-formula/lib/umd/facade.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-numfmt/lib/umd/facade.js"></script>
 
  <script src="https://unpkg.com/@univerjs/design/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/ui/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-ui/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/docs-ui/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-formula-ui/lib/umd/locale/en-US.js"></script>
  <script src="https://unpkg.com/@univerjs/sheets-numfmt-ui/lib/umd/locale/en-US.js"></script>
 
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/design/lib/index.css" />
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/ui/lib/index.css" />
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/docs-ui/lib/index.css" />
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/sheets-ui/lib/index.css" />
  <link rel="stylesheet" href="https://unpkg.com/@univerjs/sheets-formula-ui/lib/index.css" />
</head>
<body>
  <div id="app"></div>
 
  <script>
    const { Univer, LocaleType, Tools, UniverInstanceType, FUniver } = UniverCore
    const { defaultTheme } = UniverDesign
    const { UniverRenderEnginePlugin } = UniverEngineRender
    const { UniverFormulaEnginePlugin } = UniverEngineFormula
    const { UniverUIPlugin } = UniverUi
    const { UniverSheetsPlugin } = UniverSheets
    const { UniverSheetsUIPlugin } = UniverSheetsUi
    const { UniverDocsPlugin } = UniverDocs
    const { UniverDocsUIPlugin } = UniverDocsUi
    const { UniverSheetsFormulaPlugin } = UniverSheetsFormula
    const { UniverSheetsFormulaUIPlugin } = UniverSheetsFormulaUi
    const { UniverSheetsNumfmtPlugin } = UniverSheetsNumfmt
    const { UniverSheetsNumfmtUIPlugin } = UniverSheetsNumfmtUi
 
    const univer = new Univer({
      theme: defaultTheme,
      locale: LocaleType.EN_US,
      locales: {
        [LocaleType.EN_US]: Tools.deepMerge(
          {},
          UniverDesignEnUS,
          UniverUiEnUS,
          UniverSheetsEnUS,
          UniverSheetsUiEnUS,
          UniverDocsUiEnUS,
          UniverSheetsFormulaUiEnUS,
          UniverSheetsNumfmtUiEnUS
        ),
      },
    });
 
    univer.registerPlugin(UniverRenderEnginePlugin);
    univer.registerPlugin(UniverFormulaEnginePlugin);
 
    univer.registerPlugin(UniverUIPlugin, {
      container: 'app',
    });
 
    univer.registerPlugin(UniverSheetsPlugin);
    univer.registerPlugin(UniverSheetsUIPlugin);
 
    univer.registerPlugin(UniverDocsPlugin);
    univer.registerPlugin(UniverDocsUIPlugin);
 
    univer.registerPlugin(UniverSheetsFormulaPlugin);
    univer.registerPlugin(UniverSheetsFormulaUIPlugin);
    univer.registerPlugin(UniverSheetsNumfmtPlugin);
    univer.registerPlugin(UniverSheetsNumfmtUIPlugin);
 
    univer.createUnit(UniverInstanceType.UNIVER_SHEET, {});
 
    const univerAPI = FUniver.newAPI(univer);
  </script>
</body>

Getting Started: Loading, modifying and storing data

In the previous section, you have already created a Univer instance and an empty spreadsheet. However, in most cases, you will likely need to load existing data into Univer. This section will explain how to load data into Univer and retrieve data from it.

Loading Data

By calling the createUniverSheet method of univerAPI, you can create a new Workbook instance. The first parameter of the method is an object containing the data of the Workbook, which should conform to the IWorkbookData interface.

import { IWorkbookData, LocaleType } from "@univerjs/core";
 
const data: IWorkbookData = {
  id: 'test',
  sheets: {
    sheet1: {
      id: 'sheet1',
      name: 'sheet1',
      cellData: {
        0: {
          0: {
            v: 'Hello Univer!',
          },
        },
 
      },
      rowCount: 100,
      columnCount: 100,
    },
  },
  locale: LocaleType.EN_US,
  name: 'Test Workbook',
  sheetOrder: ['sheet1'],
};
const workbook = univerAPI.createUniverSheet(data);

You can further understand how to initialize spreadsheet data in Workbook Data Structure.

Modifying Data

You can use the Facade API of Univer to interact with Univer. For example, you can get the currently active sheet and update values in the specified range:

const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
const range = sheet.getRange(0, 0, 1, 1);
range.setValue(1);
🚨

Univer operates and updates states and data based on a command system, so you must use commands or the corresponding Facade API to update data properly, rather than directly modifying data. Any operation that directly modifies data in the hope of updating the view will not work as expected.

Storing Data

By calling the save method of the workbook, you can get an IWorkbookData object containing the data inside the sheet.

const savedData = univerAPI.getActiveWorkbook().save();

Next

Footnotes

  1. https://blog.npmjs.org/post/110924823920/npm-weekly-5 ↩

  2. https://pnpm.io/npmrc#auto-install-peers ↩

  3. https://github.com/yarnpkg/yarn/issues/1503 ↩

Quick StartConfigure Workbook Data