Hyperlinks

Since v1.7.0 a cell can carry a hyperlink — Excel’s Insert → Link. Links in an xlsx file are read, shown and opened on click, and written back on save; =HYPERLINK() formulas work as well.

Note: Loading links (from xlsx or ReoGrid JSON), showing them and clicking to open them work in both editions. Authoring links from code (setHyperlink, removeHyperlink, clearHyperlinks) is a Pro feature, and so is =HYPERLINK() in practice: it is a built-in function, and Lite has none, so it evaluates to #NAME? there.

Links from an xlsx file

Load the workbook and its links work — there is nothing to switch on:

await grid.loadFromUrl('/data/links.xlsx')

• Click a linked cell to open the link in a new tab.
• Click and hold (about 0.6 s) to select the cell without opening it, as in Excel. A drag that turns into a range selection does not open the link either.
• Hover shows a pointing-hand cursor and a tooltip with the address the link goes to — under the link’s screen tip, when it has one. On a cell that also has a comment, the comment is shown instead.

Excel’s blue, underlined “Hyperlink” look is ordinary cell formatting, so it comes in with the file like any other style. The link itself does not change how a cell looks.

With form mode’s clickToEdit on, a click on a linked cell follows the link rather than opening the editor.

Adding a link (Pro)

import { createReogrid } from '@reogrid/pro'

const grid = createReogrid({ workspace: '#grid' })
const ws = grid.worksheet

// The value and formatting are yours to set…
ws.cell('B2')
  .setValue('ReoGrid Web docs')
  .setStyle({ color: '#0563c1', underline: true })

// …and the link goes on by row / column (0-based): row 1, column 1 = B2
ws.setHyperlink(1, 1, 'https://web.reogrid.net/docs/')

// With a screen tip shown on hover
ws.cell('B3').setValue('Contact support')
ws.setHyperlink(2, 1, 'mailto:[email protected]', { tooltip: 'Opens your mail app' })

A link is a property of the cell: it decides what a click does and leaves the value and formatting alone, so style the cell yourself if it should look like a link. There is one link per cell; setting another replaces it.

Reading and removing

ws.getHyperlink(1, 1)     // { row: 1, col: 1, url: 'https://web.reogrid.net/docs/' }
ws.hasHyperlink(1, 1)     // true
ws.getHyperlinks()        // every link on the sheet

ws.removeHyperlink(1, 1)  // true when a link was removed
ws.clearHyperlinks()      // the number of links removed

Setting a link from code does not go on the undo stack (the same as comments), and copy & paste does not carry links.

=HYPERLINK() (Pro)

ws.cell('B5').value = '=HYPERLINK("https://web.reogrid.net/demos/", "Live demos")'

The cell shows the label — or the address, when there is no label — and a click opens the address. The address can be computed like any other argument:

ws.cell('A6').value = '1024'
ws.cell('B6').value = '=HYPERLINK("https://example.com/orders/" & A6, "Open order")'

Only a formula that is a HYPERLINK call is followed. One nested inside another function — =IF(A1>0, HYPERLINK(…), "") — shows its label but does not open.

What gets opened

• Only absolute http:, https:, mailto: and tel: addresses are opened. Anything else — javascript:, data:, a file: path, or a relative path to a file that sat next to the workbook — shows a short message on the cell instead (“This link can’t be opened here: …”). A link can arrive in a file somebody sent you, so it is never allowed to run script in your page.
• The address opens in a new tab with noopener,noreferrer: the new page gets no window.opener handle back to yours, and no Referer naming your page.
• A link to a place inside the workbook (Sheet2!A1, Excel’s “Place in This Document”) is kept and saved back, but is not followed yet — a click does nothing.

Handling a click yourself

onHyperlinkClick fires before anything is opened. Set event.cancel = true to stop ReoGrid opening the address and handle it yourself — route inside your app, ask first, or act on an address ReoGrid would refuse:

grid.onHyperlinkClick((event) => {
  // event: { row, col, url, cancel } — url exactly as stored in the cell
  const url = new URL(event.url, location.href)
  if (url.origin === location.origin) {
    event.cancel = true          // no new tab…
    location.assign(url.href)    // …navigate this one instead
  }
})

The instance-level listener follows the active sheet; worksheet.onHyperlinkClick(listener) is the per-sheet version. Both return an unsubscribe function.

Inside a sandboxed iframe

If the grid runs inside an <iframe sandbox>, the sandbox has to allow pop-ups that leave it, or the browser blocks the new tab without a word:

<iframe src="/sheet.html"
        sandbox="allow-scripts allow-popups allow-popups-to-escape-sandbox"></iframe>

Without allow-popups-to-escape-sandbox the opened page inherits the sandbox, and many sites then fail to work in it.

Links follow your edits

A link stays with its cell when rows or columns are inserted or deleted, when the sheet is sorted, and when a range is moved by drag. Deleting the row or column that holds a link deletes the link; reset() clears them all.

xlsx and ReoGrid JSON

• xlsx — <hyperlinks> is read in both editions and written by Pro’s saveAsXlsx: web and mail addresses, in-workbook locations and screen tips all round-trip.
• ReoGrid JSON — each sheet carries hyperlinks: [{ row, col, url?, location?, tooltip? }], so links survive grid.toJson() / grid.loadJson().

Hyperlinks vs the hyperlink cell type

The older hyperlink cell type (setCellType(row, col, { type: 'hyperlink' })) takes over how the cell is drawn and reads its address from the cell text (label|url). A hyperlink is a cell property instead: the cell keeps its own value, wrapping, rotation and formatting, and the link travels through xlsx. Use hyperlinks for new code; the cell type stays for existing code.

Limits

• Links to a place inside the workbook are not followed yet.
• A HYPERLINK() nested inside another function is not followed.
• A click anywhere in a linked cell opens it — Excel selects the cell instead when you click past the end of the text.
• Links set from code are not undoable, and copy & paste does not carry them.

Related

• Hyperlinks demo — links from an xlsx file, =HYPERLINK(), and a click handler, live.
• Cell Types — the older hyperlink cell type.
• Cell Comments — the other per-cell note that shows on hover.
• XLSX Import & Export — what else is read and written with the file.
• ReoGrid JSON — saving the workbook, links included.