Angular Spreadsheet Component | ng-hub-ui-spreadsheet

Editable Angular spreadsheet with Excel's keyboard, rectangular selection, a clipboard that round-trips with Excel, frozen panes and merged cells. MIT, accessible, no paid tier.

API reference

Here's the full contract for spreadsheet: everything you can bind, listen to, project and theme, gathered in one place. Wire up what you need and style what you want — it's standalone and signal-friendly.

Inputs

Dial spreadsheet in with 55 inputs. Bind them like any Angular @Input.

NameTypeDefaultDescription
rowsRequiredreadonly TRow[]—The rows, as you hold them. The sheet never writes to them.
columnsRequiredreadonly HubSpreadsheetColumn<TRow>[]—What each column shows and allows.
rowKeyRequired(row: TRow) => string—A stable name per row, so a save state follows its row across a reload.
errorsRecord<string, string>{}A validation message per cell, keyed like `states`. Owned by the host, because validation belongs to whoever knows what the data means. The cell is ringed in red and the message opens in a tooltip on hover or keyboard focus.
invalidDraftsRecord<string, string>{}Two-way. Text the reader left in a cell without it being a value the column can store, keyed like states. The cell keeps showing it, ringed, with a message saying it was not saved; reopening the cell brings it back to be corrected, Escape gives it up, and writing over the cell, or removing its row or column, drops it. Read it to stop a save that would keep the old value without a word.
statesRecord<string, HubSpreadsheetCellState>{}Save state per cell, keyed by the row key and the column alias joined by a tab.
decimalMark',' | '.'','The character this reader types decimals with. Only consulted when a pasted value carried no raw number.
emptyTextstring''What an empty sheet says.
pageSizenumber10How many rows Page Up and Page Down travel.
readonlybooleanfalseTurns off every editor, whatever the individual cells say.
frozenColumnsnumber0How many columns stay pinned to the leading edge, counted the way Excel freezes panes.
frozenRowsnumber0How many rows stay pinned below the header.
spansreadonly HubGridSpan[][]Merged blocks, each named by its top-left corner and its extent.
disjointSelectionbooleantrueWhether Ctrl-clicking (Cmd on a Mac) adds a second block to the selection instead of starting a new one. On, because it is what a spreadsheet does and because the gesture was otherwise spent: a plain click already selects, so Ctrl had nothing to say. Every block is marked, Delete empties all of them, and any ordinary click or arrow key starts the selection again. A copy happens only when the blocks line up into a table and is refused otherwise, and the fill handle is dropped while more than one is picked — a fill continues one block, and which of several has no answer.
fillHandlebooleanfalseWhether the sheet offers the fill handle at the corner of the selection. It also takes Ctrl+D (Cmd+D on a Mac) to fill down.
canUndobooleanfalseWhether undo is available. The sheet only asks; the owner keeps the history.
canRedobooleanfalseWhether redo is available.
resizableColumnsbooleanfalseWhether a reader may drag a column's trailing edge to widen or narrow it.
reorderableColumnsbooleanfalseWhether a reader may drag a header to put the column somewhere else.
reorderableRowsbooleanfalseWhether a reader may drag a row to put it somewhere else. From the keyboard, Alt+Shift with the up or down arrow moves the cursor's row one place, and the new position is read out.
rowHandleLabelstring''The accessible name of a row's drag handle.
columnWidthsRecord<string, number>{}The width of each column in pixels, keyed by alias. Two-way: the sheet writes it as the reader drags, and you may persist it.
minColumnWidthnumber48The narrowest a column may be dragged.
virtualbooleanfalseDraws only the rows the viewport covers and reserves the height of the rest, for a sheet of thousands. Off by default, and it costs something: the rows out of view are not in the document, so the browser's own find and printing reach only what is drawn, and the rows have to be of one height. Turning it on also gives the sheet a height of 24rem, because a sheet left to grow is as tall as its content and then there is nothing to virtualise.
rowHeightnumber0How tall a row is while virtualising, in pixels. Nought measures the first row drawn, which is right whenever the rows are alike. Declare it for a sheet built while hidden: a row that has never been laid out measures nought, and a window worked out from nought is the whole sheet.
formulasbooleanfalseWhether a cell whose value starts with = is a formula. Off unless asked for: a column of text may perfectly well hold =1+1 as the thing somebody wrote. A formula can name a column by its alias — =[units] * [price], =SUM([total:]) — which goes on meaning the same after a column is moved or a header rewritten, or by coordinate the way a spreadsheet writes them — =ROUND(SUM(E1:E4), 2) — which says where a column was rather than which one it is; rewriteRowFormulas() moves those with the sheet, and a reference to something deleted becomes #REF! rather than quietly reading its neighbour. A colon reads a whole column and leaves out the cell asking for it; anything else that goes round in a circle is shown as #CYCLE! rather than chased.
mergeablebooleanfalseWhether the reader may put cells together and take them apart, offered in the context menu — so it needs contextMenu too. Off unless asked for, like every structural change.
editOn'click' | 'double-click''double-click'What opens the editor with the pointer. A double click by default, the spreadsheet convention: a click picks the cell and leaves its value alone, the first character typed opens the editor and lands in it, and a cell that holds a list or a date shows a mark that opens it on one click. Set click for a sheet that exists to be typed into. Either way the editor opens on release and only when the pointer did not travel, so dragging out a range still works.
expansionTemplateRef<HubSpreadsheetExpansionContext<TRow>> | nullnullA template drawn under a row that is open, with what the row holds behind its figures.
expandedRowstring | nullnullTwo-way. Which row is open, by its key; one row at a time.
expandTogglebooleanfalseDraws a small toggle at the edges of every row that opens a detail, so the reader opens it without the owner placing a button.
expandToggleLabelstring''The accessible name of that toggle; the sheet keeps no dictionary.
rowLevel(row: TRow) => number | undefined() => 0How deep a row sits in an outline: 1 inside one fold, 2 inside two, and 0 or nothing outside every fold.
collapsedRowsreadonly string[][]Two-way. Which row groups are folded, by group id.
collapsedColumnsreadonly string[][]Two-way. Which column groups are folded, by group id.
rowToggleLabelstring''The accessible name of a row group toggle.
columnToggleLabelstring''The accessible name of a column group toggle.
direction'auto' | 'ltr' | 'rtl''auto'Which way the sheet runs. auto follows the page — a sheet inside a right-to-left article reads the way the article does, because dir is inherited — while ltr and rtl force it for a sheet that has to run against the page around it.
contextMenubooleanfalseWhether a right-click offers the menu of structural changes. Each entry still has to pass the permissions, and the menu is never opened empty.
columns[].kind'text' | 'number' | 'currency' | 'date' | 'boolean' | 'select''text'How the column shows its values and reads back what is typed. A select column opens a list and refuses anything not on it; a boolean draws a checkbox that turns over in one click; a date opens a date field.
columns[].formulastring—A formula every cell of this column is worked out from, declared in code rather than held by the data — a line total, a tax, a running balance. The other way round from a formula a reader types, which is a value the row holds and can be changed like any other. Cells of such a column cannot be typed into at all: replacing one would lose the formula for that row alone, and nobody notices until the totals stop adding up. Needs formulas on the sheet.
columns[].placeholderstring—A hint shown in an empty cell of this column while the pointer rests on it. Never in place of a value: a column of hints always on screen reads as a column of content.
columns[].appendHubSpreadsheetAppend<TRow>—A second value shown after the main one and picked from a short list: the unit after a quantity, the kind of discount after its figure. A change to it arrives as a commit whose column key is append.key. Copy writes both parts; CSV and XLSX export only the main value.
columns[].optionsreadonly HubSpreadsheetOption[]—The answers a select column offers. A cell shows the matching label rather than the stored value, and falls back to the raw value when nothing matches, so a row holding a retired option stays readable.
structureHubSpreadsheetStructureOptions<TRow>{}Which structural changes the reader may ask for. Everything is refused until allowed.
retiredColumnKeysreadonly string[][]Aliases of columns that were deleted, so a new one never inherits a dead identity.
hubSpreadsheetCell (directive on ng-template)Requiredstring—Alias of the column whose cells are drawn by this template instead of the default renderer. Bound as the directive attribute itself: hubSpreadsheetCell="state".
hubSpreadsheetCellRows (hubSpreadsheetCell)readonly TRow[][]The same rows given to the sheet. Nothing reads them; they only let the compiler type the row in the template context.
hubSpreadsheetCellAction (hubSpreadsheetCell)string | ((row: TRow) => boolean)''Marks the column as one whose cells open onto something and gives the accessible name of the way in. A function decides per row. Enter is kept for opening and the press is reported through opened.
hubSpreadsheetEditor (directive on ng-template)Requiredstring—Alias of the column whose editor is drawn by this template instead of the built-in one. Bound as the directive attribute itself: hubSpreadsheetEditor="assignee".
hubSpreadsheetEditorRows (hubSpreadsheetEditor)readonly TRow[][]The same rows given to the sheet. Nothing reads them; they only let the compiler type the row in the template context.
hubSpreadsheetControl (directive on ng-container)RequiredHubSpreadsheetControlConfig—Renders a cell editor through the control adapter registered with provideHubSpreadsheetControls(). The config is read once, when the editor opens.
value (hub-spreadsheet-field, ng-hub-ui-spreadsheet/signals)TRow[][]Two-way model (use [(value)]) holding the rows as the Signal Forms field value; written back whenever the reader changes a cell. Emits valueChange.
disabled (hub-spreadsheet-field)booleanfalseBound by the Signal Forms FormField directive; disables every editor.
errors (hub-spreadsheet-field)readonly ValidationError.WithOptionalFieldTree[][]Bound by the Signal Forms FormField directive. Only the array field's own errors arrive here, so they are shown as a whole, not per cell. hub-spreadsheet-field also takes columns, rowKey, states, decimalMark, emptyText, pageSize, readonly, frozenColumns, frozenRows and spans with the same meaning as on hub-spreadsheet, and emits selectionChange.

Outputs

React to what spreadsheet does — 21 events to hook your logic onto.

NameTypeDescription
commitHubSpreadsheetCommit<TRow>A cell took a new value, and it differs from the one it held.
pastedHubSpreadsheetPaste<TRow>A block was pasted, with counts of what fell outside the sheet and what was not a number.
clearedHubSpreadsheetCellRef<TRow>[]Delete or Backspace was pressed over several cells, or over a list or yes/no cell; carries the editable cells it covered. A single text cell opens its editor empty instead.
openedHubSpreadsheetCellRef<TRow>A cell's action was used — with the pointer, or Enter where there is no field to edit.
selectionChangeHubGridRange | nullThe selected rectangle changed.
filledHubSpreadsheetPaste<TRow>A drag of the fill handle finished, reported as one event for the whole gesture.
undoRequestedvoidThe reader asked to undo.
redoRequestedvoidThe reader asked to redo.
columnMoved{ from: number; to: number; key: string; keys: string[] }A column was dropped somewhere else. Reported, not applied: the payload carries the aliases already reordered.
rowMoved{ from: number; to: number; key: string; keys: string[] }A row was dropped somewhere else. Reported, not applied: the payload carries the keys already reordered.
invalidDraftsChangeRecord<string, string>The unsaved text changed: the reader left a cell with text it cannot store, or corrected, gave up or wrote over one.
mergeRequestedHubSpreadsheetMergeRequestThe reader asked to merge a selection. Carries the block to create and the anchors of the blocks it swallows, because appending without dropping those leaves two blocks claiming the same cell. applySpanMerge() does it in a line.
unmergeRequestedreadonly HubGridCoords[]The reader asked to take apart the blocks their selection touches, named by their anchors. applySpanUnmerge() applies it.
selectionRangesChangereadonly HubGridRange[]Every rectangle of the selection, whenever it changes. Beside selectionChange, which keeps reporting the one the cursor is in: a host showing the sum of what is selected needs all of them, and one showing “you are in B4” does not. One entry unless blocks were held with Ctrl.
insertRequestedHubSpreadsheetInsertRequestThe reader asked to add rows or columns. A paste longer than the sheet asks for the rows it runs past this way, with count set to how many.
deleteRequestedHubSpreadsheetDeleteRequestThe reader asked to remove rows or columns, naming the aliases at stake.
valueChange (hub-spreadsheet-field)TRow[]Emitted by the two-way value model when the rows change.
columnWidthsChangeRecord<string, number>Emitted by the two-way columnWidths model when the reader resizes a column.
expandedRowChangestring | nullEmitted by the two-way expandedRow model when a row expands or collapses.
collapsedColumnsChangereadonly string[]Emitted by the two-way collapsedColumns model when column groups fold or unfold.
collapsedRowsChangereadonly string[]Emitted by the two-way collapsedRows model when row groups fold or unfold.

Methods

Drive spreadsheet from code — 19 methods on its programmatic surface.

NameSignatureReturnsDescription
HubSpreadsheetComponent.focusCellfocusCell(rowKey: string, column?: string): void—Puts the cursor and the keyboard on a cell, by row key and column alias. Waits for a row the host has just added, and with no alias lands on the row's first cell the reader can type into, so the next key opens it.
HubSpreadsheetComponent.editCelleditCell(rowKey: string, column?: string): void—Opens a cell's editor from code, keeping its value, as F2 does. Waits for a row the host has just added, like focusCell; on a cell that cannot be edited it only puts the cursor there.
sheetToXlsxsheetToXlsx<TRow>(rows, columns, options?: HubXlsxOptions): Uint8ArrayUint8ArrayThe sheet as a real .xlsx, as bytes. Figures stay figures and a date column becomes a date, which is what a CSV cannot carry. Writes what the cell shows — a list column exports its label, a formula its result — unless values: 'stored' asks for what the rows hold.
downloadXlsxdownloadXlsx(filename: string, bytes: Uint8Array): void—Hands the reader that workbook to save, adding .xlsx to the name if it is missing. Here because every host writes the same six lines and forgets to release the object URL.
xlsxToRecordsxlsxToRecords<TRow>(bytes, columns, options?: HubXlsxReadOptions): Promise<Array<Record<string, string>>>Promise<Array<Record<string, string>>>Reads a workbook's first sheet into rows keyed by column alias, undoing the two things a CSV never does: shared strings, and dates stored as a count of days. Asynchronous, because a real workbook is compressed and the decompressor is the platform's.
sheetToCsvsheetToCsv<TRow>(rows, columns, options?: HubCsvOptions): stringstringThe sheet as CSV. With no delimiter given it comes from the decimal mark — a comma cannot separate what it also punctuates — so a file read where figures are written 1.234,56 gets semicolons.
downloadTextdownloadText(filename: string, text: string, type?: string): void—Hands the reader a text file to save, with the byte-order mark that makes a spreadsheet open it as UTF-8 rather than as mojibake.
csvToRecordscsvToRecords<TRow>(text, columns, options?: HubCsvOptions): Array<Record<string, string>>Array<Record<string, string>>Reads a CSV into rows keyed by column alias, sniffing the separator on the first line rather than assuming it. Headings are matched by header first and alias second, ignoring case and surrounding space.
sheetValuessheetValues<TRow>(rows, columns, options?: HubSheetValuesOptions): HubSpreadsheetValue[][]HubSpreadsheetValue[][]What every cell holds, with the formulas worked out and a failed one spelled the way a spreadsheet spells it. What both exporters read, exposed for a host that writes its own file.
evaluateSheetevaluateSheet<TRow>(input: HubFormulaSheetInput<TRow>): HubFormulaSheetHubFormulaSheetRuns every formula in a sheet, in whatever order the dependencies demand, worked out lazily and remembered. A circle is caught the moment it closes rather than chased. Exported for a host that wants the answers without drawing them.
rewriteRowFormulasrewriteRowFormulas<TRow extends object>(rows, change: HubFormulaShapeChange): TRow[]TRow[]Moves every coordinate in the rows after the sheet changes shape: a column moved, or rows or columns inserted or deleted. A reference to something deleted becomes #REF! rather than quietly reading its neighbour. The host calls it, because the rows are the host's.
mergeRequestFormergeRequestFor(spans, range): HubSpreadsheetMergeRequest | nullHubSpreadsheetMergeRequest | nullThe block a selection would become, and the anchors it swallows; null for a single cell. The swallowed anchors are the part a host gets wrong on its own — appended without dropping them, two blocks claim the same cell.
applySpanMergeapplySpanMerge(spans, request: HubSpreadsheetMergeRequest): HubGridSpan[]HubGridSpan[]The list of blocks after that merge, with the swallowed ones dropped.
applySpanUnmergeapplySpanUnmerge(spans, anchors: readonly HubGridCoords[]): HubGridSpan[]HubGridSpan[]The list of blocks after those are taken apart.
spreadsheetRecordsspreadsheetRecords<TRow>(rows, columns): HubSpreadsheetRecord[]HubSpreadsheetRecord[]Every row as plain data keyed by column alias, so a consumer works with { price: 12, units: 3 } instead of mapping coordinates onto its own fields by position.
parseForColumnparseForColumn<TRow>(text, column, decimalMark: ',' | '.'): HubSpreadsheetValue | undefinedHubSpreadsheetValue | undefinedWhat a typed or pasted string is worth in a column: the value, null for an empty cell, and undefined for something the column cannot hold — which lets a caller refuse rather than store rubbish.
nextColumnKeynextColumnKey(taken: Iterable<string>, prefix?: string): stringstringAn alias that has never belonged to another column, so a new column never reuses a retired name and no stored reference can resolve to the wrong thing.
danglingColumnKeysdanglingColumnKeys<TRow>(referenced: Iterable<string>, columns): string[]string[]References that no longer resolve to a column, which is what a deletion would leave pointing at nothing.
provideHubSpreadsheetControlsprovideHubSpreadsheetControls(adapter: HubSpreadsheetControlsAdapter): EnvironmentProvidersEnvironmentProvidersRegisters a control adapter, so every list column opens with it — searchable, already open, with the character that opened the cell in its search box. Without one the sheet draws its native list, which is what keeps the library installable on its own.

Templates

Make it yours — 3 template slots let you project custom markup.

NameDescriptionExample
hubSpreadsheetEditorReplaces the editor of one column, named by its alias. The template is handed the value, a commit and cancel pair, draft to hold a value without closing, and `seed` — the character that opened the cell when the reader opened it by typing, which belongs in a picker's search box. The sheet closes it as it closes its own editor: Escape as it was, once a list open inside it has closed; Tab with what draft holds; and focus going elsewhere likewise, unless it goes into the popup one of its controls names through aria-controls, as hub-select's list does. Every other key is the editor's, Enter included. The sheet takes no dependency on whatever you put inside.<ng-template hubSpreadsheetEditor="assignee" let-value let-seed="seed" let-commit="commit"> <hub-select [items]="people" autoOpen [initialSearchTerm]="seed ?? null" [ngModel]="value" (ngModelChange)="commit($event)" /> </ng-template>
hubSpreadsheetCellDraws one column's cells yourself while they are not being edited: a badge for a state, an avatar beside a name, a row of actions. The sibling of hubSpreadsheetEditor, which covers the other half of a cell's life. The clipboard still carries the value rather than the drawing, and the cell is still what the keyboard is on. Hand the rows over through hubSpreadsheetCellRows and the compiler knows what `row` is.<ng-template hubSpreadsheetCell="state" let-value> <hub-badge variant="soft" [color]="colourOf(value)">{{ labelOf(value) }}</hub-badge> </ng-template>
hubSpreadsheetHeaderDraws one column's header title yourself: an icon beside the name, a button that edits the column. The sibling of hubSpreadsheetCell for the header. The <th> stays the sheet's, with its width, freezing, sticky position and check-all box. A button, link or field inside it can be pressed without dragging the column. The template gets the column, its index, its key and the plain header.<ng-template hubSpreadsheetHeader="price" let-column> {{ column.header }} <button type="button" (click)="editPrice()">Edit</button> </ng-template>