Web SDK

Hyperlink

Hyperlinks are used to quickly navigate and access content within spreadsheets, such as internal worksheets, cells, and external web pages or email addresses.

Preview

Preset Mode

Installation

Shell
pnpm add @univerjs/preset-sheets-hyper-link

Usage

TypeScript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'import { UniverSheetsHyperLinkPreset } from '@univerjs/preset-sheets-hyper-link'import UniverPresetSheetsHyperLinkEnUS from '@univerjs/preset-sheets-hyper-link/locales/en-US'import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'import '@univerjs/preset-sheets-core/lib/index.css'import '@univerjs/preset-sheets-hyper-link/lib/index.css'const { univerAPI } = createUniver({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      UniverPresetSheetsCoreEnUS,      UniverPresetSheetsHyperLinkEnUS,     ),  },  presets: [    UniverSheetsCorePreset(),    UniverSheetsHyperLinkPreset(),   ],})

Presets and Configuration

TypeScript
UniverSheetsHyperLinkPreset({  // Customize the way external links are opened  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

Complete configuration options can be found in IUniverSheetsHyperLinkPresetConfig.

Plugin Mode

Installation

Shell
pnpm add @univerjs/sheets-hyper-link @univerjs/sheets-hyper-link-ui

Usage

TypeScript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'import { UniverSheetsHyperLinkPlugin } from '@univerjs/sheets-hyper-link'import { UniverSheetsHyperLinkUIPlugin } from '@univerjs/sheets-hyper-link-ui'import SheetsHyperLinkUIEnUS from '@univerjs/sheets-hyper-link-ui/locale/en-US'import '@univerjs/sheets-hyper-link-ui/lib/index.css'import '@univerjs/sheets-hyper-link/facade'import '@univerjs/sheets-hyper-link-ui/facade'const univer = new Univer({  locale: LocaleType.EN_US,  locales: {    [LocaleType.EN_US]: mergeLocales(      SheetsHyperLinkUIEnUS,     ),  },})univer.registerPlugin(UniverSheetsHyperLinkPlugin)univer.registerPlugin(UniverSheetsHyperLinkUIPlugin)

Plugins and Configuration

TypeScript
univer.registerPlugin(UniverSheetsHyperLinkUIPlugin, {  // Customize the way external links are opened  urlHandler: {    navigateToOtherWebsite: url => window.open(`${url}?utm_source=univer`, '_blank'),  },})

Complete configuration options can be found in IUniverSheetsHyperLinkUIConfig.

Facade API

Complete Facade API type definitions can be found in the FacadeAPI.

Importing

Plugin mode note

Only plugin mode requires manually importing the Facade package. Preset mode already includes the corresponding Facade package, so no extra import is needed.

TypeScript
import '@univerjs/sheets-hyper-link/facade'

The navigateToSheetHyperlink API is provided by the UI plugin, so import:

TypeScript
import '@univerjs/sheets-hyper-link-ui/facade'

Create HyperLink

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// Create a hyperlink to Univer on cell A1const fRange = fWorksheet.getRange('A1')await fRange.setHyperLink('//', 'Univer')// Create a hyperlink to active sheet range B2:D4 on cell A2const fRange2 = fWorksheet.getRange('A2')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await fRange2.setHyperLink(rangeUrl, 'Link to B2:D4')// Create a hyperlink to another sheet range on cell A3const anotherSheet = fWorkbook.getSheetByName('Another Sheet')if (anotherSheet) {  const fRange3 = fWorksheet.getRange('A3')  const anotherSheetUrl = anotherSheet.getUrl()  await fRange3.setHyperLink(anotherSheetUrl, 'Link to Another Sheet')}// Create a hyperlink to a defined name on cell A4const fRange4 = fWorksheet.getRange('A4')const definedNameHyperlinkUrl = fWorkbook.getUrlOfDefineName('MyDefinedName')await fRange4.setHyperLink(definedNameHyperlinkUrl, 'Link to MyDefinedName')

Get/Update/Cancel HyperLink

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const fWorksheet = fWorkbook.getSheetByName('Sheet1')if (!fWorksheet) return// Get all hyperlinks in the range A1:D10const fRange = fWorksheet.getRange('A1:D10')const hyperlinks = fRange.getHyperLinks()console.log(hyperlinks)// Update the hyperlink on cell A1const cellA1 = fWorksheet.getRange('A1')const rangeUrl = fWorksheet.getRange('B2:D4').getUrl()await cellA1.updateHyperLink(rangeUrl, 'Link to B2:D4')// Clear all hyperlinks in the range A1:D10fRange.cancelHyperLink()// Or clear a specific hyperlink in the range A1:D10if (hyperlinks.length > 1) {  fRange.cancelHyperLink(hyperlinks[1])}

Build/Parse/Jump HyperLink

TypeScript
const fWorkbook = univerAPI.getActiveWorkbook()const sheets = fWorkbook.getSheets()// Build a hyperlink url pointing to cell F6 of the first sheetconst hyperlinkUrl = sheets[0].getRange('F6').getUrl()// Parse the hyperlinkconst hyperlinkInfo = fWorkbook.parseSheetHyperlink(hyperlinkUrl)console.log(hyperlinkInfo)// Switch to the second sheetfWorkbook.setActiveSheet(sheets[1])console.log(fWorkbook.getActiveSheet().getSheetName())// Jump to the hyperlink after 3 secondsawait new Promise(resolve => setTimeout(resolve, 3000))fWorkbook.navigateToSheetHyperlink(hyperlinkUrl)console.log(fWorkbook.getActiveSheet().getSheetName())

Event Listeners

Full event type definitions, please refer to Events.

You can listen to hyperlink-related events using univerAPI.addEvent():

Link Addition Event

univerAPI.Event.BeforeSheetLinkAdd: Triggered before adding a link

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkAdd, (params) => {  const { workbook, worksheet, row, col, link } = params  // Cancel the sheet link add operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

Link Update Event

univerAPI.Event.BeforeSheetLinkUpdate: Triggered before updating a link

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkUpdate, (params) => {  const { workbook, worksheet, row, column, id, payload } = params  // Cancel the sheet link update operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

Link Deletion Event

univerAPI.Event.BeforeSheetLinkCancel: Triggered before canceling a link

TypeScript
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetLinkCancel, (params) => {  const { workbook, worksheet, row, column, id } = params  // Cancel the sheet link cancel operation  params.cancel = true})// Remove the event listener, use `disposable.dispose()`

Each event includes the following common parameters:

  • workbook: Current workbook instance
  • worksheet: Current worksheet instance
  • row: Row index of the cell containing the link
  • column: Column index of the cell containing the link (note: BeforeSheetLinkAdd uses col instead of column)

Special parameters:

  • BeforeSheetLinkAdd event includes link: The link to be added
  • BeforeSheetLinkUpdate event includes:
    • id: Link identifier
    • payload: New link data
  • BeforeSheetLinkCancel event includes id: Link identifier to be removed

All event callbacks can use params.cancel = true to prevent the corresponding operation.

How is this guide?

© 2026 DreamNum Co., Ltd.