Installation & Basic Usage

Univer is a framework for electronic document applications, and it is assembled from plugins. The core remains small, and an application adds only the modules it needs. The trade-off is a more involved setup, particularly when working with Univer for the first time.

To reduce that effort, Univer provides two integration styles: plugin mode and preset mode. A preset is a set of plugins configured in advance, so without custom extensions both modes provide the same capabilities.

Caution

  • Keep dependency versions in sync. In either mode, every dependency must resolve to the same version.
  • Mix plugins and presets with care. If a preset already includes a plugin, do not import that plugin separately. Otherwise plugin conflicts or unexpected feature behavior may occur.

The two modes differ as follows:

Plugin modePreset mode
You import the required facade packages yourselfFacade packages come with the preset
You control the registration order of plugins that provide the same functionalityThe preset already handles registration order
Plugins can be lazy-loaded on demandConfigured presets load synchronously during initialization

Preset mode keeps setup short: a single import brings in a bundle of preconfigured plugins. For deep customization or extensions, use plugin mode, which allows plugins to be combined and configured individually.

Let an agent help with integration (optional)

Use univer-integrate when adding the Web SDK to an existing application. It guides a coding agent through preset or plugin setup, editor initialization, and Facade API usage.

Bash
npx skills add dream-num/skills --skill univer-integrate

Run this command in the project directory that the agent has open. Add -g to use the skill across projects, or specify an agent with -a codex or -a claude-code. Then list the installed skills:

Bash
npx skills list

The list should include univer-integrate. If the skill is missing, verify that SKILL.md exists in the installation path and reopen the agent session if necessary.

Older tutorials may reference dream-num/univer-sdk-skills. Use the current dream-num/skills command shown above; the skill name remains univer-integrate. Verify the SDK baseline that the skill expects, and integrate against the current documentation and the versions installed in your project.

Setting Up via Plugin Mode

Univer delivers its features as plugins. A few core plugins are required for the product to function; the remaining plugins are imported as needed. This section builds a minimal Univer Sheets application manually and registers its plugins one by one.

Unlike preset mode, plugin mode does not include the Facade API1 by default. The Facade-related parts of the code below are optional and can be removed when not needed.

Using Package Manager

Installation

Univer uses React for its views (this does not prevent using it in Vue or Angular) and Rxjs for data streams. Both libraries are widely used in modern front-end development, so Univer treats them as peerDependencies2. Package managers handle peer dependencies differently, and several details require attention:

  • With npm, use npm@7 or later. npm@3 ~ npm@6 do not install peerDependencies3 correctly.
  • With pnpm, use pnpm@8 or later. On pnpm@6 ~ pnpm@7, setting auto-install-peers=true 4 may resolve dependency installation issues.
  • With yarn, install the missing peerDependencies5 manually. The installation commands below already include them.
Shell
pnpm add @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

Caution

  • Not every plugin includes a facade package, locale files, and styles. The documentation for each feature states what it provides.
  • Stylesheet order matters. Import the CSS of @univerjs/design and @univerjs/ui before the styles of any other plugin.
  1. Import Univer's styles, locale files, and the plugins the application requires:

    TypeScript
    import { LocaleType, mergeLocales, Univer, UniverInstanceType } from '@univerjs/core'import { FUniver } from '@univerjs/core/facade'import DesignEnUS from '@univerjs/design/locale/en-US'import { UniverDocsPlugin } from '@univerjs/docs'import { UniverDocsUIPlugin } from '@univerjs/docs-ui'import DocsUIEnUS from '@univerjs/docs-ui/locale/en-US'import { UniverFormulaEnginePlugin } from '@univerjs/engine-formula'import { UniverRenderEnginePlugin } from '@univerjs/engine-render'import { UniverSheetsPlugin } from '@univerjs/sheets'import { UniverSheetsFormulaPlugin } from '@univerjs/sheets-formula'import { UniverSheetsFormulaUIPlugin } from '@univerjs/sheets-formula-ui'import SheetsFormulaUIEnUS from '@univerjs/sheets-formula-ui/locale/en-US'import { UniverSheetsNumfmtPlugin } from '@univerjs/sheets-numfmt'import { UniverSheetsNumfmtUIPlugin } from '@univerjs/sheets-numfmt-ui'import SheetsNumfmtUIEnUS from '@univerjs/sheets-numfmt-ui/locale/en-US'import { UniverSheetsUIPlugin } from '@univerjs/sheets-ui'import SheetsUIEnUS from '@univerjs/sheets-ui/locale/en-US'import SheetsEnUS from '@univerjs/sheets/locale/en-US'import { UniverUIPlugin } from '@univerjs/ui'import UIEnUS from '@univerjs/ui/locale/en-US'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'import '@univerjs/sheets-numfmt-ui/lib/index.css'
  2. To use the Facade API, import the facade packages at this point. This step is optional but recommended:

    TypeScript
    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'
  3. Then create the Univer instance and register the plugins:

    TypeScript
    const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      DesignEnUS,      UIEnUS,      DocsUIEnUS,      SheetsEnUS,      SheetsUIEnUS,      SheetsFormulaUIEnUS,      SheetsNumfmtUIEnUS,    ),  },})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.registerPlugin(UniverSheetsNumfmtPlugin)univer.registerPlugin(UniverSheetsNumfmtUIPlugin)univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})const univerAPI = FUniver.newAPI(univer)

Plugin configuration

UniverUIPlugin

  • container
    string | HTMLElement
    Element to mount into, or its DOM ID.

UniverWatermarkPlugin

  • textWatermarkSettings
    object
    Text watermark settings.
    • content
      stringDefault: ''
      Text to display.
    • fontSize
      numberDefault: 16
      Font size, in pixels.

univer.registerPlugin and univer.registerPlugins Methods

The univer.registerPlugin method registers a plugin with the Univer instance. Call it after the instance has been created.

Pass the plugin and its options: univer.registerPlugin(Plugin, options). Plugin is the plugin to register, and options are optional configuration items that differ from one plugin to another.

To register several plugins at once, pass an array to univer.registerPlugins. This approach is useful when plugins are managed in one place.

TypeScript
univer.registerPlugins([  UniverRenderEnginePlugin,  UniverFormulaEnginePlugin,  [UniverUIPlugin, {    container: 'app',  }],  UniverDocsPlugin,  UniverDocsUIPlugin,  UniverSheetsPlugin,  UniverSheetsUIPlugin,  UniverSheetsFormulaPlugin,  UniverSheetsFormulaUIPlugin,  UniverSheetsNumfmtPlugin,  UniverSheetsNumfmtUIPlugin,])

Lazy Loading Plugins

A key advantage of plugin mode is control over when plugins load. A common pattern loads only the essential plugins during initialization and defers the rest until after the first render.

TypeScript
// ...univer.createUnit(UniverInstanceType.UNIVER_SHEET, {})import('@univerjs/watermark').then(({ UniverWatermarkPlugin }) => {  univer.registerPlugin(UniverWatermarkPlugin, {    textWatermarkSettings: {      content: 'Hello, Univer!',      fontSize: 36,    },  })})

The official demo applies the same optimization and is worth reviewing.

Mobile support

These examples require SDK packages that export the mobile plugins listed below. Keep all @univerjs/* and @univerjs-pro/* dependencies on the same version.

The mobile UI plugins provide touch controls in Univer Sheets.6 Choose the UI mode before creating the editor.

Mobile support for Sheets remains experimental. Test the features your application requires on the devices you target.

In the plugin-mode example above, replace the UI imports and registrations with those below before createUnit(). Do not append them to a desktop editor that has already been initialized. Retain the model plugins, engines, locale files, CSS, and Facade imports. Desktop and mobile classes are named exports of the same package entry.

UniverMobileUIPlugin

  • container
    string | HTMLElement
    Element to mount into, or its DOM ID.
  • disableAutoFocus
    trueDefault: true
    Prevents the editor from taking focus at startup.
TypeScript
import { UniverDocsMobileUIPlugin } from '@univerjs/docs-ui'import { UniverSheetsFormulaMobileUIPlugin } from '@univerjs/sheets-formula-ui'import { UniverSheetsNumfmtMobileUIPlugin } from '@univerjs/sheets-numfmt-ui'import { UniverSheetsMobileUIPlugin } from '@univerjs/sheets-ui'import { UniverMobileUIPlugin } from '@univerjs/ui'univer.registerPlugin(UniverMobileUIPlugin, { container: 'app' })univer.registerPlugin(UniverDocsMobileUIPlugin)univer.registerPlugin(UniverSheetsMobileUIPlugin)univer.registerPlugin(UniverSheetsFormulaMobileUIPlugin)univer.registerPlugin(UniverSheetsNumfmtMobileUIPlugin)

On mobile, also replace UniverDocsUIPlugin with UniverDocsMobileUIPlugin so that documents inside cells can be edited, and register it before UniverSheetsMobileUIPlugin.

UniverSheetsCorePreset and UniverDocsCorePreset currently register desktop UI plugins and have no mobile: true option. For mobile, assemble the plugins explicitly. Adding mobile plugins after a desktop preset does not replace the preset's UI.

Plugin mapping

Register only the features you use, and retain their model plugins and required dependencies. A mobile UI export does not mean that the desktop and mobile interfaces provide identical controls. Pro features still require the appropriate license. Features that require a backend need integration with Univer Server SDK on the application side.

PackageDesktop registrationMobile registration
@univerjs/uiUniverUIPluginUniverMobileUIPlugin
@univerjs/docs-uiUniverDocsUIPluginUniverDocsMobileUIPlugin
@univerjs/sheets-uiUniverSheetsUIPluginUniverSheetsMobileUIPlugin
@univerjs/sheets-formula-uiUniverSheetsFormulaUIPluginUniverSheetsFormulaMobileUIPlugin
@univerjs/sheets-numfmt-uiUniverSheetsNumfmtUIPluginUniverSheetsNumfmtMobileUIPlugin
@univerjs/drawing-uiUniverDrawingUIPluginUniverDrawingMobileUIPlugin
@univerjs/thread-comment-uiUniverThreadCommentUIPluginUniverThreadCommentMobileUIPlugin
@univerjs-pro/shape-editor-uiUniverShapeEditorUIPluginUniverShapeEditorMobileUIPlugin
@univerjs-pro/chart-uiUniverChartUIPluginUniverChartMobileUIPlugin
@univerjs-pro/exchange-clientUniverExchangeClientPluginUniverExchangeClientMobileUIPlugin
@univerjs/sheets-conditional-formatting-uiUniverSheetsConditionalFormattingUIPluginUniverSheetsConditionalFormattingMobileUIPlugin
@univerjs/sheets-crosshair-highlightUniverSheetsCrosshairHighlightPluginUniverSheetsCrosshairHighlightMobileUIPlugin
@univerjs/sheets-data-validation-uiUniverSheetsDataValidationUIPluginUniverSheetsDataValidationMobileUIPlugin
@univerjs/sheets-drawing-uiUniverSheetsDrawingUIPluginUniverSheetsDrawingMobileUIPlugin
@univerjs/sheets-filter-uiUniverSheetsFilterUIPluginUniverSheetsFilterMobileUIPlugin
@univerjs/sheets-find-replaceUniverSheetsFindReplacePluginUniverSheetsFindReplaceMobileUIPlugin
@univerjs/sheets-hyper-link-uiUniverSheetsHyperLinkUIPluginUniverSheetsHyperLinkMobileUIPlugin
@univerjs/sheets-sort-uiUniverSheetsSortUIPluginUniverSheetsSortMobileUIPlugin
@univerjs/sheets-table-uiUniverSheetsTableUIPluginUniverSheetsTableMobileUIPlugin
@univerjs/sheets-thread-comment-uiUniverSheetsThreadCommentUIPluginUniverSheetsThreadCommentMobileUIPlugin
@univerjs-pro/sheets-chart-uiUniverSheetsChartUIPluginUniverSheetsChartMobileUIPlugin
@univerjs-pro/sheets-exchange-clientUniverSheetsExchangeClientPluginUniverSheetsExchangeClientMobileUIPlugin
@univerjs-pro/sheets-history-uiUniverSheetsHistoryUIPluginUniverSheetsHistoryMobileUIPlugin
@univerjs-pro/sheets-outline-uiUniverSheetsOutlineUIPluginUniverSheetsOutlineMobileUIPlugin
@univerjs-pro/sheets-pivot-uiUniverSheetsPivotTableUIPluginUniverSheetsPivotTableMobileUIPlugin
@univerjs-pro/sheets-printUniverSheetsPrintPluginUniverSheetsPrintMobileUIPlugin
@univerjs-pro/sheets-shape-uiUniverSheetsShapeUIPluginUniverSheetsShapeMobileUIPlugin
@univerjs-pro/sheets-sparkline-uiUniverSheetSparklineUIPluginUniverSheetSparklineMobileUIPlugin
@univerjs/find-replaceUniverFindReplacePluginUniverFindReplaceMobileUIPlugin

Container and touch interaction

Set an explicit height for the container and configure the page viewport. 100dvh tracks the dynamic viewport height. In the target mobile browsers, verify scrolling, pinch zoom, text selection, clipboard access, and the on-screen keyboard. Resizing a desktop editor alone does not select mobile plugins.

UniverMobileUIPlugin defaults to disableAutoFocus: true, so the editor does not take focus automatically during initialization.

HTML
<meta name="viewport" content="width=device-width, initial-scale=1" /><div id="app" style="height: 100dvh"></div>

Import from CDN

If you prefer not to use a package manager, or want to try Univer quickly, you can load Univer from a CDN. For details, see Using Univer via CDN.

Setting Up via Preset Mode

Preset mode produces a running Univer Sheets application in under twenty lines of code.

Using Package Manager

If the project already uses modern front-end tooling, integrating Univer is straightforward. Use a build tool with solid ES Module support, such as Vite, esbuild, or Webpack 5. Older tools such as Webpack 4 may require additional configuration.

Installation

Install @univerjs/presets with your package manager:

Shell
pnpm add @univerjs/presets @univerjs/preset-sheets-core

Usage

If the build tool does not support the exports field in package.json (common with Webpack 4), change the mapped paths to the actual paths manually.

These two files are sufficient to start a Univer Sheets application:

HTML
<div id="app" style="height: 600px"></div>
TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'const { univer, univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,    ),  },  presets: [    UniverSheetsCorePreset({      container: 'app',    }),  ],})univerAPI.createWorkbook({})

The returned univerAPI object is the Univer Facade API. It is the interface through which you call the features that Univer provides.

You can also import UniverSheetsCorePreset from @univerjs/presets/preset-sheets-core, provided that the build tool supports the exports field in package.json.

Preset configuration

UniverSheetsCorePreset

  • container
    string | HTMLElementDefault: 'app'
    Element to mount into, or its DOM ID.

createUniver Method

createUniver accepts a configuration object that contains settings for Univer, such as language, theme, and plugins. It returns an object that contains the Univer instance and the Univer Facade API instance.

The main properties are:

  • locale: the language environment, as a LocaleType value.
  • locales: an object of locale packs, keyed by language environment.
  • theme: an optional theme object.
  • presets: the presets to register, such as UniverSheetsCorePreset.
  • plugins: plugins to register in addition to the presets.

When a plugin does not belong to any preset package, or when you write your own, register it through the plugins property. You can also call univer.registerPlugin after obtaining the Univer instance.

For details on createUniver, see API Reference / createUniver.

Import from CDN

If you do not want to use a package manager, or want to try Univer quickly, you can load it from a CDN. Details are provided in Using Univer via CDN.

Other Releases

Beyond stable releases, Univer provides alpha, beta, and nightly channels. These builds offer early access to new features before they are released as stable. More features also bring more risk: these versions may contain bugs, incomplete functionality, or unstable behavior. Avoid them in production where possible.

Alpha / Beta Release

When the Univer team completes a new feature or a significant change, it may pre-release the change to the alpha or beta channel. Install an alpha or beta build with:

Shell
pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta version

If you encounter a problem or have feedback while using an alpha or beta version, report it to the Univer team through GitHub Issues.

Next Steps

  • Basic Concepts explains the concepts this page uses.
  • Features describes what Univer can do and how to work with spreadsheet data.

Footnotes

  1. Facade is the application-facing API over registered plugins. Importing a Facade entry adds API methods; it does not register the feature plugin itself. ↩

  2. peerDependencies declare dependencies that the host application must provide with compatible versions. They let Univer share libraries such as React instead of bundling a separate copy. ↩

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

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

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

  6. A mobile UI plugin selects touch controls and mobile services during initialization. It does not automatically detect the device or switch an existing instance when the window is resized. To change modes, preserve the document state, dispose of the old instance and initialize the chosen plugin set. ↩

How is this guide?

© 2026 DreamNum Co., Ltd.