<universal-sheet>

The <universal-sheet> web component — an .xlsx editor that draws the grid to a canvas with the look of Microsoft Excel: column widths and row heights from the workbook, number formats, fonts, borders, merged cells, conditional formatting, charts, images and shapes. Formulas are recalculated by a built-in engine with Excel's functions.

Package @universal-office/sheet

• Opens .xlsx and .xls (Excel 97–2003, converted in memory); saves .xlsx, rewriting only what was edited
• Inline cell editing typed like Excel (numbers, dates, percentages, currency, booleans, formulas) with function autocomplete
• Recalculation of dependent cells across all sheets on every edit
• Formula language and number separators follow the user's locale (=SUM(A1,1.5) or =SOMA(A1;1,5))
• Range selection, undo/redo, copy and paste (formulas adjusted), fill down/right, find and replace
• Formatting saved to the .xlsx: font, fill, borders, alignment, wrap, number formats, merge cells, column widths and row heights, hide/unhide, frozen panes, gridlines
• Optional built-in bars, like Excel: a compact toolbar (default) or a ribbon, formula bar, sheet tabs and a status bar with sum/average/count; English, Portuguese and Spanish UI; light and dark
• Frozen panes, hidden rows/columns, hyperlinks, comments
• Zoom, resizable rows and columns (double-click to autofit)

Just want to edit spreadsheets? The same editor is Universal Sheet (Beta) in the ready-to-run desktop app Universal Office (Beta) — Write, Sheet and Slides in one install — for Windows, macOS and Linux: download it from the releases page — or try it live in your browser.

Installation

npm install @universal-office/sheet

All the code is inside the package; its only dependency is @universal-office/font-files (pinned to an exact version), the open fonts. Serve these paths:

import { FontResolver } from '@universal-office/sheet';

FontResolver.shared().configure({ baseUrl: '/node_modules/@universal-office/font-files' });

const sheet = document.querySelector('universal-sheet');
sheet.loadXlsx(new Uint8Array(await (await fetch('/budget.xlsx')).arrayBuffer()));
sheet.addEventListener('us-selection', (e) => console.log(e.detail.ref, e.detail.edit));

<universal-sheet style="display:block; height:100vh"></universal-sheet>

Give the element a size with CSS — it fills its box. For a complete spreadsheet app with menus, formula bar and sheet tabs, add the bars:

<universal-sheet topbar bottombar style="display:block; height:100vh"></universal-sheet>

Attributes and properties

Built-in bars

topbar and bottombar turn the element into a complete spreadsheet app — nothing to wire. The bars are a chunk loaded on demand: without the attributes the element loads none of it and looks exactly as before. They are built with the same toolbar framework as <universal-write> (@universal-office/ui), so both products share menus, dialogs, keyboard handling, colors and plugins.

• Compact (toolbar="compact", default): the workbook title above the menus (editable — it is the name suggested when saving), a Save .xlsx button, and one toolbar row — undo, redo, print, zoom, currency, percent, decimals, number formats, font, size, bold, italic, strikethrough, font color, fill color, borders, merge, alignment, wrap, AutoSum; when space runs out the lowest-priority groups collapse into their own buttons and then into "⋮", and the menus into "☰".
• Ribbon (toolbar="ribbon"): quick access toolbar (save, undo, redo), File menu and the Home tab (Clipboard, Font, Alignment, Number, Cells, Editing groups, with the Format Cells launchers), Insert (sheet, function, AutoSum), Formulas (Function Library, Calculate Now), View (formula bar, gridlines, sheet tabs, status bar, zoom, Freeze Panes, theme, accent, toolbar style) and Help.
• Formula bar under either bar: the Name Box (shows the selection; type a reference — B12, A1:C5, Sheet2!A1 — and Enter to go there), the fx button (Insert Function) and the formula of the active cell with function autocomplete. View › Formula bar hides it.
• Bottom bar (bottombar): sheet tabs with previous/next and + (Insert Sheet), and the status bar with Average · Count · Sum of the selection (when two or more cells are selected, like Excel) and the zoom slider.
• Menus: - File — New, Open (.xlsx, .xlsm, .xls), Save, Save as, Download as PDF,

OpenDocument Spreadsheet (.ods), CSV and TSV (active sheet), Web page, Markdown, XML Spreadsheet 2003; Print (a PDF of the workbook); Properties. - Edit — Undo, Redo, Cut, Copy, Paste, Paste values, Fill (down, right), Clear (all, formats, contents), Select all, Find, Replace, Go to. - View — Formula bar, Gridlines, Sheet tabs, Status bar, Freeze (panes at the active cell, top row, first column, unfreeze), Zoom, previous/next sheet, Theme, Accent color, Toolbar (compact or ribbon). - Insert — Sheet, Function, AutoSum (Sum, Average, Count numbers, Max, Min). - Format — Number (General, Number, Currency, Accounting, Short date, Long date, Time, Percentage, Fraction, Scientific, Text, More number formats…, Comma style, Percent style, Increase/Decrease decimal), Text (bold, italic, underline, strikethrough, bigger/smaller), Font color, Fill color, Alignment (horizontal, vertical, indent, wrap), Merge cells (merge & center, merge across, merge cells, unmerge), Borders (bottom, top, left, right, none, all, outside, thick outside), Rows and Columns (height/width, AutoFit, hide, unhide), Format Cells… (Number, Alignment, Font and Fill tabs), Clear formats. - Tools — Calculate now. Help — Keyboard shortcuts, About.

• Context menu on the grid (cut, copy, paste, paste values, insert function, clear, merge, rows, columns, Format Cells), drag and drop of a spreadsheet to open it, unsaved-changes prompt on leaving the page.
• A command whose API the element does not have stays hidden.

Light and dark

Like <universal-write>: the bars follow the **CSS color-scheme of their context** (it crosses the shadow DOM) and every color is a --u-color-* token or a light-dark() color, so the switch is pure CSS and live; theme forces it. Without accent, the bars use the page's --u-color-* tokens when it defines them, otherwise the element's own palette (green). The grid stays light, like Excel's.

CSS variables: --us-font (UI font), --us-background (one background for the bars, formula bar, sheet tabs and status bar; default --u-color-surface-container-low), --uo-bar-bg, --uo-bar-container (the toolbar pill), --uo-accent, --us-formula-font. Parts: topbar, bottombar, toolbar, titlebar, menubar, toolrow, tabs, ribbon, menu, popover, dialog, notice, formula-bar, sheet-tabs, statusbar.

Host integration

What only the host application can do comes in through the optional sheet.host object (an Electron shell, for example); without it the bars use the browser (File System Access, downloads, a PDF window for printing, beforeunload):

sheet.host = {
  openFile: () => bridge.open(),              // → { name, bytes, path? } | null
  saveFile: (bytes, { name, saveAs, path }) => bridge.save(bytes, name, path), // → name | { name, path } | null
  exportFile: (kind, name, data) => bridge.export(kind, name, data),        // data() → bytes/text after the user picks
  print: ({ pdf, title }) => bridge.print(pdf, title),                      // system print dialog
  listFonts: bridge.listFonts, resolveFonts: bridge.resolveFonts,           // OS fonts
  setDirty: (dirty, name) => bridge.setDirty(dirty, name),                  // confirm on close
  onSaveBeforeClose: (cb) => bridge.onSaveBeforeClose(cb),
  closeWindow: () => bridge.close(),
  setTitleTheme: (dark, barColor) => bridge.setTitleTheme(dark, barColor),  // window buttons
  setTitle: (title) => { document.title = title; },
  windowControlsOverlay: true, // frameless window: reserve the OS window buttons, drag by the title row
};

openWorkbook(sheet, bytes, name, { path }) (exported) opens a workbook the way File › Open does: title, file name and, with path, where Save writes. When the page saves and opens files itself, handle the cancelable us-save-request (detail: { saveAs, format }) and us-open-request events and call preventDefault(): the bars then do nothing for those actions. sheet.setNotice(element, { tone }) shows a notice band between the title row and the tools (tone: info · warning · error; null removes it).

Plugins

The same model as <universal-write>: install per instance with sheet.use(plugin) / sheet.unuse(id), or for every instance with UniversalSheetElement.register(plugin) / unregister(id). A plugin may declare setup({ sheet }) (returns its cleanup) and toolbar({ sheet, lang, theme, ui }), returning commands and their places in the bars — { commands, compact: { title, leading, menus, groups, trailing }, ribbon: { title, tabs, groups: [{ tab, … }], qat } }; items accept before: '<id>'. ui is the widget kit (createBarButton, createBarIcon, createBarRow, barCss…), also available as loadBarKit(). Labels take a string or { en, pt, es }; es is optional, and without it the Spanish UI shows the English text.

sheet.use({
  id: 'acme.audit',
  toolbar: () => ({
    commands: [{ id: 'acme:audit', label: { en: 'Audit', pt: 'Auditar' }, icon: 'info', run: () => audit(sheet) }],
    compact: { groups: [{ id: 'acme', label: 'Acme', items: ['acme:audit'] }] },
    ribbon: { groups: [{ tab: 'home', id: 'acme', label: 'Acme', cells: [{ cmd: 'acme:audit', size: 'large' }] }] },
  }),
});

Methods

A minimal formula bar of your own (the built-in one does this):

const bar = document.querySelector('#formula');
sheet.attachFormulaBar(bar);
sheet.addEventListener('us-selection', () => { bar.value = sheet.activeCellEditText; });
bar.addEventListener('keydown', (e) => {
  if (e.key === 'Enter') sheet.setActiveCellText(bar.value);
});

Events

Fonts

The default font of a workbook (Aptos Narrow, Calibri…) defines the column widths, so it matters. Families resolve, in order: fonts the browser can see by name (installed or declared with @font-face) → metric-compatible open substitutes from the folder given to FontResolver (Calibri → Carlito, Cambria → Caladea, Arial → Liberation Sans, Times New Roman → Liberation Serif, Courier New → Liberation Mono) → Liberation Sans. Those fonts come in @universal-office/font-files, installed with this package: serve its folder and point FontResolver.shared().configure({ baseUrl }) at it. The PDF export uses the workbook's Normal font when its file is available, otherwise Liberation Sans.

Keyboard and mouse

Arrows move (leaving merged cells by their edge), Shift+arrows extend the selection, Ctrl+arrows jump to the edge of the data, Home · End go to the first and last column, Ctrl+Home · Ctrl+End to A1 and the last used cell, PageUp · PageDown move 10 rows, Tab · Shift+Tab move sideways, Ctrl+A selects all, Ctrl+Space · Shift+Space the column · row, Ctrl+PageUp · Ctrl+PageDown switch sheets. Typing starts editing, F2 or Enter edit the current content, Delete · Backspace clear the selection, Ctrl+Z · Ctrl+Y undo and redo, Ctrl+C · Ctrl+X · Ctrl+V copy, cut and paste. While editing: Enter commits and moves down, Tab · Shift+Tab commit and move sideways, Escape cancels. Click and drag (or Shift+click) select a range; click a column letter or row number to select it (drag for several); the corner selects all. Wheel scrolls (Shift for horizontal); drag a header border to resize, double-click it to autofit; double-click a cell to edit; hover a red-cornered cell to read its comment.

With topbar, Excel's shortcuts for the bar commands: Ctrl+O open, Ctrl+S save, F12 save as, Ctrl+P print, Ctrl+F find, Ctrl+H replace, Ctrl+G · F5 go to, Ctrl+B · I · U · 5 bold, italic, underline, strikethrough, Ctrl+1 Format Cells, Ctrl+D · Ctrl+R fill down/right, Alt+= AutoSum, Shift+F3 insert function, F9 calculate, Shift+F11 insert sheet, Ctrl+9 · Ctrl+0 hide rows · columns, Ctrl+Shift+9 unhide rows, Ctrl+Shift+1 · 2 · 3 · 4 · 5 · 6 number, time, date, currency, percent, scientific formats, Ctrl+Shift+` General, Ctrl+Shift+7 outside borders, Ctrl+Shift+- no border (keys by position, so they work on any keyboard layout). Help › Keyboard shortcuts lists them all.

Current limitations

Not yet available (and so not in the bars): inserting or deleting rows, columns and cells; sorting and filtering; inserting charts, images, shapes, comments and hyperlinks; editing conditional formatting, data validation and cell styles; renaming, deleting and moving sheets; Paste Special beyond values; page setup and print options (print and PDF use the converter's layout); right-to-left editing (right-to-left sheets are drawn only by renderRegionToCanvas); hiding the row and column headings.

License

MIT. The fonts (@universal-office/font-files) are under the SIL OFL 1.1 and the Apache License 2.0.