Columns

Sparklines

Add native Excel sparkline columns from typed source columns, groups, or dynamic scopes.

Use type: "sparkline" when a column should render a native Excel mini chart for each row — a 12-month trend next to each account, a win/loss strip next to each sales rep.

These are real Excel sparklines, not images: they recalculate when the source cells change, and they respect the workbook theme. The sparkline target can be a sparkline-only column, or it can share a cell with a normal accessor or formula value.

Basic usage

import { createExcelSchema
 } from "typed-xlsx";

type Row
 = {
  account
: string;
  jan
: number;
  feb
: number;
  mar
: number;
};

const schema
 = createExcelSchema
<Row
>()
  .column
("account", { accessor
: "account" })
  .column
("jan", { accessor
: "jan" })
  .column
("feb", { accessor
: "feb" })
  .column
("mar", { accessor
: "mar" })
  .column
("trend", {
    type
: "sparkline",
    header
: "Trend",
    width
: 18,
    source
: ["jan", "feb", "mar"],
    sparklineType
: "line",
    emptyCells
: "zero",
    style
: {
      line
: { color
: "#2563EB", weight
: 1.25 },
      dots
: false,
      high
: { color
: "#16A34A" },
      low
: { color
: "#DC2626" },
    },
  })
  .build
();

The source column IDs are checked by TypeScript. A sparkline can only reference columns declared before the sparkline column.

Sparklines read better with a little vertical room. Set defaults: { rowHeight: 30 } on the table to give every body row a minimum height — see Table style defaults.

Source forms

Use an explicit list when you want exact columns:

.column("trend", {
  type: "sparkline",
  source: ["jan", "feb", "mar"],
})

Use a range when the source columns are contiguous:

.column("trend", {
  type: "sparkline",
  source: { from: "jan", to: "mar" },
})

Use a group or dynamic scope when the columns are produced structurally:

.column("trend", {
  type: "sparkline",
  source: { group: "months" },
})

.column("trend", {
  type: "sparkline",
  source: { dynamic: "months" },
})

At export time, selected columns must still resolve to a non-empty contiguous range. If a source column is excluded by select, typed-xlsx throws a clear error instead of emitting a broken workbook.

Styling and themes

Sparkline colors come from the active spreadsheet theme by default. A table theme or schema theme can provide these tokens:

sparklineSeries
sparklineMarkers
sparklineFirst
sparklineLast
sparklineHigh
sparklineLow
sparklineNegative
sparklineAxis

Column-level style options override the theme:

import { createExcelSchema
 } from "typed-xlsx";

const schema
 = createExcelSchema
<{ jan
: number; feb
: number; mar
: number }>()
  .column
("jan", { accessor
: "jan" })
  .column
("feb", { accessor
: "feb" })
  .column
("mar", { accessor
: "mar" })
  .column
("trend", {
    type
: "sparkline",
    source
: { from
: "jan", to
: "mar" },
    style
: {
      line
: { color
: "#2563EB", weight
: 1.25 },
      dots
: { visible
: true, color
: "#1D4ED8" },
      first
: { color
: "#64748B" },
      last
: { color
: "#10B981" },
      high
: { color
: "#16A34A" },
      low
: { color
: "#DC2626" },
      axis
: {
        visible
: true,
        color
: "#94A3B8",
        min
: { value
: 0 },
        max
: "group",
      },
    },
  })
  .build
();

For column and win/loss sparklines, use style.series for the main bar color and style.negative for negative values:

import { createExcelSchema
 } from "typed-xlsx";

const schema
 = createExcelSchema
<{ won
: number; lost
: number; open
: number }>()
  .column
("won", { accessor
: "won" })
  .column
("lost", { accessor
: "lost" })
  .column
("open", { accessor
: "open" })
  .column
("mix", {
    type
: "sparkline",
    source
: ["won", "lost", "open"],
    sparklineType
: "winLoss",
    style
: {
      series
: "#16A34A",
      negative
: { color
: "#DC2626" },
      axis
: { visible
: true, color
: "#64748B" },
    },
  })
  .build
();

Option reference

Sparkline renderer options:

Option	Values	What it controls
`type`	`"sparkline"`	Selects the sparkline renderer
`source`	list, range, group, dynamic scope	Which columns feed the mini chart (see Source forms)
`sparklineType`	`"line"` \| `"column"` \| `"winLoss"`	Chart shape, defaults to `"line"`
`emptyCells`	`"gap"` \| `"zero"` \| `"span"`	How Excel draws missing values
`style`	object	Colors, markers, and axis (see below)

Everything visual lives under style:

Style option	Accepts	What it controls
`style.series`	color string	Main series color (bars for column/winLoss)
`style.line`	`{ color?, weight? }`	Line color and weight in points (line type)
`style.markers` / `style.dots`	boolean or `{ visible?, color? }`	Data point markers (`dots` is an alias)
`style.first` / `style.last`	boolean or `{ visible?, color? }`	Highlight the first / last point
`style.high` / `style.low`	boolean or `{ visible?, color? }`	Highlight the highest / lowest point
`style.negative`	boolean or `{ visible?, color? }`	Highlight negative values
`style.axis`	boolean or `{ visible?, color?, min?, max? }`	Horizontal axis visibility, color, and bounds
`style.hidden`	boolean	Include values from hidden rows/columns
`style.rightToLeft`	boolean	Plot the series right-to-left

Axis bounds (style.axis.min / style.axis.max) can be "individual", "group", "custom", or { type?, value? } — matching Excel's own axis scaling modes.

Hyperlinks

Add native Excel hyperlinks without changing the rendered cell value.

Images

Add embedded worksheet images or URL-backed Excel IMAGE formulas.