Using Custom Components in Univer

Univer provides multiple ways to integrate custom components, allowing you to extend and customize Univer’s functionality. This guide will cover several common methods.

Prerequisites: Custom Components in Univer

In Univer, we use ComponentManager to manage custom DOM components.
Before using the following methods, you need to register your components first.

Registering a React component

const ReactComponent = (props: any) => {
  console.log('ReactComponent', props);
  return <div style={{ width: 100, height: 100, background: '#fff' }}>Popup Content</div>
}
univerAPI.getComponentManager().register(
  'myComponentKey',
  ReactComponent,
);

Registering a Vue3 component

const Vue3Component = defineComponent({
  setup(props) {
    console.log('Vue3Component', props);
    return () => <div style={{ width: 100, height: 100, background: '#fff' }}>Popup Content</div>
  }
});
 
univerAPI.getComponentManager().register(
  'myComponentKey',
  Vue3Component,
  {
    framework: 'vue3',
  }
);

1. Using Custom Components in the Sidebar

`openSidebar` Method 0.3.0+

Use workbook.openSidebar(params:ISidebarMethodOptions) to open a sidebar containing custom components in the Univer interface.
ISidebarMethodOptions: Complete parameter definition

// You should register components at an appropriate time (e.g., when Univer is loaded)
// This is a React component. For Vue3 components, see Prerequisites section above
univerAPI.getComponentManager().register(
  'mySidebarComponentKey',
  () => <div style={{ width: 100, height: 100, background: '#fff' }}>Popup Content</div>
);
 
const sidebar = workbook.openSidebar({
  header: { title: 'My Sidebar' },
  children: { label: 'mySidebarComponentKey' },
  onClose: () => {
      console.log('close');
  },
  width: 360,
});
 
// Close sidebar later
sidebar.dispose();

2. Using Custom Components in Dialogs

`openDialog` Method 0.3.0+

Use workbook.openDialog(params: IDialogPartMethodOptions) to open a dialog containing custom components.
IDialogPartMethodOptions: Complete parameter definition

// You should register components at an appropriate time (e.g., when Univer is loaded)
// This is a React component. For Vue3 components, see Prerequisites section above
univerAPI.getComponentManager().register(
  'myDialogComponentKey',
  () => <div style={{ width: 100, height: 100, background: '#fff' }}>Popup Content</div>
);
 
const dialog = workbook.openDialog({
  // unique id
  id: 'myDialog',
  draggable: true,
  width: 300,
  title: { title: 'Dialog title' },
  children: { 
    label: 'myDialogComponentKey'
  },
  destroyOnClose: true,
  preservePositionOnDestroy: true,
  onClose: () => {},
});
 
// Close dialog later
dialog.dispose();

3. Attaching Popups to Cells 0.2.10+

`attachPopup` Method

A Popup is a temporary DOM element attached to a cell, typically used to display temporary status information. It doesn’t support persistent storage.
Use range.attachPopup() to attach custom popups to specific cell ranges.
Popups will snap to the cell’s four edges and automatically adjust position and direction if obscured.

const sheet = univerAPI.getActiveWorkbook().getActiveSheet();
const range = sheet.getRange(0, 0, 10, 10); // A1:J10
 
// You should register components at an appropriate time (e.g., when Univer is loaded)
// This is a React component. For Vue3 components, see Prerequisites section above
univerAPI.getComponentManager().register(
  'myPopup',
  () => <div style={{ width: 100, height: 100, background: '#fff' }}>Popup Content</div>
);
 
// Attach popup to the first cell of the range
// If disposable is null, popup attachment failed
const disposeable = range.attachPopup({
  // componentKey must be a component or key of a registered component
  componentKey: 'myPopup',
});
 
// Remove popup
disposable.dispose();

4. Adding Floating DOM to Worksheet 0.2.10+

`addFloatDomToPosition` Method

Requires the @univerjs/sheets-drawing-ui plugin.
Floating DOM is a draggable component hovering over the sheet that supports persistent storage.
Must be called after Univer has finished rendering.
componentKey must be a registered component ID or React/Vue3 component.
Complete parameter definition

demo

const worksheet = univerAPI.getActiveWorkbook().getActiveSheet();
 
// You should register components at an appropriate time (e.g., when Univer is loaded)
// This is a React component. For Vue3 components, see Prerequisites section above
univerAPI.getComponentManager().register(
  'myFloatDom',
  ({ data }) => (
    <div style={{ width: '100%', height: '100%', background: '#fff' }}>
      popup content
      {data?.label}
    </div>
  ),
);
 
// Add a floating DOM
// If disposable is null, floating DOM addition failed
const disposeable = worksheet.addFloatDomToPosition({
  // componentKey must be a component or key of a registered component
  componentKey: 'myFloatDom',
  initPosition: {
    startX: 100,
    endX: 200,
    startY: 100,
    endY: 200,
  },
 
  // Component data
  data: {
    label: 'hahah',
  },
});
 
// Remove floating DOM
disposeable.dispose();

5. Attaching Alert Popups 0.3.0+

`attachAlertPopup` Method

Use range.attachAlertPopup() to attach an alert popup to the starting cell of a specified range.

const range = sheet.getRange("A1:B2");
const alertDisposable = range.attachAlertPopup({
  key: "myAlert",
  title: "This is a warning!",
  message: "This is a warning!",
  width: 300,
  height: 200,
  // 0: Information
  // 1: Warning
  // 2: Error
  type: 0
});
 
// Remove alert later
alertDisposable.dispose();

Important Notes

Ensure Univer has finished rendering before using these methods.
Make sure components are properly registered before use.
Use the dispose() method to clean up and remove added components to prevent memory leaks.

With these methods, you can flexibly integrate various custom components in Univer to enhance and customize its functionality.

Clipboard Default Style