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 mode | Preset mode |
|---|---|
| You import the required facade packages yourself | Facade packages come with the preset |
| You control the registration order of plugins that provide the same functionality | The preset already handles registration order |
| Plugins can be lazy-loaded on demand | Configured 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.
npx skills add dream-num/skills --skill univer-integrateRun 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:
npx skills listThe 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=true4 may resolve dependency installation issues. - With yarn, install the missing
peerDependencies5 manually. The installation commands below already include them.
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/uinpm 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/uiyarn 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 react react-dom rxjsbun 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/uiUsage
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/designand@univerjs/uibefore the styles of any other plugin.
Import Univer's styles, locale files, and the plugins the application requires:
TypeScriptimport { 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'To use the Facade API, import the facade packages at this point. This step is optional but recommended:
TypeScriptimport '@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'Then create the Univer instance and register the plugins:
TypeScriptconst 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
containerstring | HTMLElementElement to mount into, or its DOM ID.
UniverWatermarkPlugin
textWatermarkSettingsobjectText watermark settings.contentstringDefault:''Text to display.fontSizenumberDefault:16Font 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.
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.
// ...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
containerstring | HTMLElementElement to mount into, or its DOM ID.disableAutoFocustrueDefault:truePrevents the editor from taking focus at startup.
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.
| Package | Desktop registration | Mobile registration |
|---|---|---|
@univerjs/ui | UniverUIPlugin | UniverMobileUIPlugin |
@univerjs/docs-ui | UniverDocsUIPlugin | UniverDocsMobileUIPlugin |
@univerjs/sheets-ui | UniverSheetsUIPlugin | UniverSheetsMobileUIPlugin |
@univerjs/sheets-formula-ui | UniverSheetsFormulaUIPlugin | UniverSheetsFormulaMobileUIPlugin |
@univerjs/sheets-numfmt-ui | UniverSheetsNumfmtUIPlugin | UniverSheetsNumfmtMobileUIPlugin |
@univerjs/drawing-ui | UniverDrawingUIPlugin | UniverDrawingMobileUIPlugin |
@univerjs/thread-comment-ui | UniverThreadCommentUIPlugin | UniverThreadCommentMobileUIPlugin |
@univerjs-pro/shape-editor-ui | UniverShapeEditorUIPlugin | UniverShapeEditorMobileUIPlugin |
@univerjs-pro/chart-ui | UniverChartUIPlugin | UniverChartMobileUIPlugin |
@univerjs-pro/exchange-client | UniverExchangeClientPlugin | UniverExchangeClientMobileUIPlugin |
@univerjs/sheets-conditional-formatting-ui | UniverSheetsConditionalFormattingUIPlugin | UniverSheetsConditionalFormattingMobileUIPlugin |
@univerjs/sheets-crosshair-highlight | UniverSheetsCrosshairHighlightPlugin | UniverSheetsCrosshairHighlightMobileUIPlugin |
@univerjs/sheets-data-validation-ui | UniverSheetsDataValidationUIPlugin | UniverSheetsDataValidationMobileUIPlugin |
@univerjs/sheets-drawing-ui | UniverSheetsDrawingUIPlugin | UniverSheetsDrawingMobileUIPlugin |
@univerjs/sheets-filter-ui | UniverSheetsFilterUIPlugin | UniverSheetsFilterMobileUIPlugin |
@univerjs/sheets-find-replace | UniverSheetsFindReplacePlugin | UniverSheetsFindReplaceMobileUIPlugin |
@univerjs/sheets-hyper-link-ui | UniverSheetsHyperLinkUIPlugin | UniverSheetsHyperLinkMobileUIPlugin |
@univerjs/sheets-sort-ui | UniverSheetsSortUIPlugin | UniverSheetsSortMobileUIPlugin |
@univerjs/sheets-table-ui | UniverSheetsTableUIPlugin | UniverSheetsTableMobileUIPlugin |
@univerjs/sheets-thread-comment-ui | UniverSheetsThreadCommentUIPlugin | UniverSheetsThreadCommentMobileUIPlugin |
@univerjs-pro/sheets-chart-ui | UniverSheetsChartUIPlugin | UniverSheetsChartMobileUIPlugin |
@univerjs-pro/sheets-exchange-client | UniverSheetsExchangeClientPlugin | UniverSheetsExchangeClientMobileUIPlugin |
@univerjs-pro/sheets-history-ui | UniverSheetsHistoryUIPlugin | UniverSheetsHistoryMobileUIPlugin |
@univerjs-pro/sheets-outline-ui | UniverSheetsOutlineUIPlugin | UniverSheetsOutlineMobileUIPlugin |
@univerjs-pro/sheets-pivot-ui | UniverSheetsPivotTableUIPlugin | UniverSheetsPivotTableMobileUIPlugin |
@univerjs-pro/sheets-print | UniverSheetsPrintPlugin | UniverSheetsPrintMobileUIPlugin |
@univerjs-pro/sheets-shape-ui | UniverSheetsShapeUIPlugin | UniverSheetsShapeMobileUIPlugin |
@univerjs-pro/sheets-sparkline-ui | UniverSheetSparklineUIPlugin | UniverSheetSparklineMobileUIPlugin |
@univerjs/find-replace | UniverFindReplacePlugin | UniverFindReplaceMobileUIPlugin |
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.
<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:
pnpm add @univerjs/presets @univerjs/preset-sheets-corenpm install @univerjs/presets @univerjs/preset-sheets-coreyarn add @univerjs/presets @univerjs/preset-sheets-corebun add @univerjs/presets @univerjs/preset-sheets-coreUsage
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:
<div id="app" style="height: 600px"></div>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
containerstring | 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 aLocaleTypevalue.locales: an object of locale packs, keyed by language environment.theme: an optional theme object.presets: the presets to register, such asUniverSheetsCorePreset.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:
pnpm add @univerjs/<package-name>@alpha # Alpha version
pnpm add @univerjs/<package-name>@beta # Beta versionnpm install @univerjs/<package-name>@alpha # Alpha version
npm install @univerjs/<package-name>@beta # Beta versionyarn add @univerjs/<package-name>@alpha # Alpha version
yarn add @univerjs/<package-name>@beta # Beta versionbun add @univerjs/<package-name>@alpha # Alpha version
bun add @univerjs/<package-name>@beta # Beta versionIf 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
-
Facade is the application-facing API over registered plugins. Importing a Facade entry adds API methods; it does not register the feature plugin itself. ↩
-
peerDependenciesdeclare dependencies that the host application must provide with compatible versions. They let Univer share libraries such as React instead of bundling a separate copy. ↩ -
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?