Hyperlinks and Tooltips
File Format Support (click to show)
Traditional spreadsheet software, including Excel, support "Cell Links". The entire cell text is clickable.
Modern spreadsheet software, including Numbers, support "Span Links". Links are applied to text fragments within the cell content. This mirrors HTML semantics.
Formats | Link | Tooltip | Link Type |
---|---|---|---|
XLSX / XLSM | ✔ | ✔ | Cell Link |
XLSB | ✔ | ✔ | Cell Link |
XLS (BIFF8) | ✔ | ✔ | Cell Link |
XLML | ✔ | ✔ | Cell Link |
ODS / FODS / UOS | ✔ | Span Link | |
HTML | ✔ | ✕ | Span Link |
NUMBERS | ✔ | ✕ | Span Link |
X (✕) marks features that are not supported by the file formats. For example, the NUMBERS file format does not support custom tooltips.
For "Span Link" formats, parsers apply the first hyperlink to the entire cell and writers apply the hyperlink to the entire cell text.
Hyperlinks are stored in the l
key of cell objects. The Target
field of the
hyperlink object is the target of the link, including the URI fragment. Tooltips
are stored in the Tooltip
field and are displayed when hovering over the text.
For example, the following snippet creates a link from cell A1
to
https://sheetjs.com with the tip "Find us @ SheetJS.com!"
:
ws["A1"].l = { Target: "https://sheetjs.com", Tooltip: "Find us @ SheetJS.com!" };
Following traditional software, hyperlinks are applied to entire cell objects. Some formats (including HTML) attach links to text spans. The parsers apply the first link to the entire cell. Writers apply links to the entire cell text.
Excel does not automatically style hyperlinks. They will be displayed using the default cell style.
SheetJS Pro Basic includes support for general hyperlink styling.Live Example (click to hide)
Extract all links from a file (click to show)
The following example iterates through each worksheet and each cell to find all links. The table shows sheet name, cell address, and target for each link.
Remote Links
HTTP and HTTPS links can be used directly:
ws["A2"].l = { Target: "https://docs.sheetjs.com/docs/csf/features/hyperlinks" };
ws["A3"].l = { Target: "http://localhost:7262/yes_localhost_works" };
Excel also supports mailto
email links with subject line:
ws["A4"].l = { Target: "mailto:[email protected]" };
ws["A5"].l = { Target: "mailto:[email protected]?subject=Test Subject" };
Live Example (click to show)
This demo creates a XLSX spreadsheet with a mailto
email link. The email
address input in the form never leaves your machine.
Local Links
Links to absolute paths should use the file://
URI scheme:
ws["B1"].l = { Target: "file:///SheetJS/t.xlsx" }; /* Link to /SheetJS/t.xlsx */
ws["B2"].l = { Target: "file:///c:/SheetJS.xlsx" }; /* Link to c:\SheetJS.xlsx */
Links to relative paths can be specified without a scheme:
ws["B3"].l = { Target: "SheetJS.xlsb" }; /* Link to SheetJS.xlsb */
ws["B4"].l = { Target: "../SheetJS.xlsm" }; /* Link to ../SheetJS.xlsm */
Relative Paths have undefined behavior in the SpreadsheetML 2003 format. Excel
2019 will treat a ..\
parent mark as two levels up.
Internal Links
Links where the target is a cell or range or defined name in the same workbook ("Internal Links") are marked with a leading hash character:
ws["C1"].l = { Target: "#E2" }; /* Link to cell E2 */
ws["C2"].l = { Target: "#Sheet2!E2" }; /* Link to cell E2 in sheet Sheet2 */
ws["C3"].l = { Target: "#SheetJSDName" }; /* Link to Defined Name */
Live Example (click to show)
This demo creates a workbook with two worksheets. In the first worksheet:
- Cell
A1
("Same") will link to the rangeB2:D4
in the first sheet - Cell
B1
("Cross") will link to the rangeB2:D4
in the second sheet - Cell
C1
("Name") will link to the range in the defined nameSheetJSDN
The defined name SheetJSDN
points to the range A1:B2
in the second sheet.
Some third-party tools like Google Sheets do not correctly parse hyperlinks in XLSX documents. A workaround was added in library version 0.18.12.
Tooltips
Tooltips are attached to hyperlink information. There is no way to specify a tooltip without assigning a cell link.
Excel has an undocumented tooltip length limit of 255 characters.
Writing longer tooltips is currently permitted by the library but the generated files will not open in Excel.
HTML
The HTML DOM parser1 will process <a>
links in the table.
Live Example (click to hide)
This example uses table_to_book
to generate a SheetJS workbook object from a
HTML table. The hyperlink in the second row will be parsed as a cell-level link.
The HTML writer2 will generate <a>
links.
Live Example (click to hide)
This example creates a worksheet where A1
has a link and B1
does not. The
sheet_to_html
function generates an HTML table where the topleft table cell
has a standard HTML link.
- The primary SheetJS DOM parsing methods are
table_to_book
,table_to_sheet
, andsheet_add_dom
↩ - HTML strings can be written using
bookType: "html"
in thewrite
orwriteFile
methods or by using the dedicatedsheet_to_html
utility function↩