Installation & Basic Usage

If you are using Univer for the first time, we recommend starting with Presets. In this chapter, we will introduce how to install Univer with Presets. If you are familiar with Univer or want to import plugins more flexibly (e.g., lazy loading some plugins), you can refer to the Advanced Installation chapter.

💗

In most chapters of the document, we will introduce Presets and advanced installation methods. Please choose the appropriate method for installation.

Using Package Managers

If you are familiar with modern frontend development, using package managers to build applications containing Univer will be a good choice.

We recommend using build tools such as Vite, esbuild, or Webpack 5 that have good support for ES Modules to build Univer applications. If you are using other build tools like Webpack 4, you may require some additional configurations. For more information, please refer to Read More and the Troubleshooting.

Installation

Choose your package manager to install @unvierjs/presets:

npm install @univerjs/presets

pnpm add @univerjs/presets

yarn add @univerjs/presets

bun add @univerjs/presets

Usage

With just a few lines of code, you can start a spreadsheet application and load the basic functionality of a spreadsheet:

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';
 
const { univerAPI } = createUniver({
  locale: LocaleType.EN_US,
  locales: {
    enUS: UniverPresetSheetsCoreEnUS,
  },
  theme: defaultTheme,
  presets: [
    UniverSheetsCorePreset({
      container: 'app',
    }),
  ],
});
 
univerAPI.createUniverSheet({ name: 'Test Sheet' });

Update

If you are using pnpm, you can use the following command to update all plugins:

pnpm update "@univerjs/presets" @latest

Import by a `<script>` Tag

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

Example

Current mainstream CDN service providers (such as jsDelivr and unpkg) support Univer’s UMD build, and you can include these resources in your HTML file:

<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" />
</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
  </script>
</body>

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

Specifying Versions

Both unpkg and jsDeliver support specifying specific versions of resources. For example, if you want to use version 0.1.16 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

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, UniverInstanceType } 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);

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();

Basic Concepts - Learn about the basic concepts of Univer.
Presets - Learn how to use presets to quickly build a Univer application.
Workbook Data Structure - Learn how to initialize spreadsheet data.
Features - Learn about the features of Univer and how to manipulate data.

Quick Start Configure Workbook Data