1. Spreadsheet docs
  2. Developers

Charts and shapes from code

Add charts and shapes, then find them, rename, move, resize, retitle, recolour, layer and remove them through object handles.

Charts, shapes, pictures, text boxes and connectors are objects that float over a sheet. From code you add them with addChart and addShape, and then work with them through handles: small objects with a name, a position, alternative text and the properties of their kind. Every change through a handle is one undo step, in a mounted workbook and a headless one alike.

Add a chart and change it

JavaScript

import { mountWorkbook } from '@8sheets/core';

const wb = await mountWorkbook(document.querySelector('#sheet'));
const sheet = wb.activeSheet;
sheet.range('A1').values = [['Month', 'Revenue', 'Cost'], ['Jan', 120, 80], ['Feb', 135, 82], ['Mar', 150, 90]];

const chart = sheet.chart(sheet.addChart('column', 'A1:C4', { x: 260, y: 10, w: 420, h: 260 }));
chart.name = 'Revenue chart';
chart.title = 'Revenue and cost, Q1';
chart.altText = 'Column chart of revenue and cost for January to March';
chart.setRect({ x: 280, w: 480 });   // fields left out keep their value

const badge = sheet.shape(sheet.addShape('roundRect', { x: 20, y: 120, w: 180, h: 50 }));
badge.text = 'Draft';
badge.fill = '#FDE68A';
badge.bringToFront();

React

import { Sheet } from '@8sheets/react';

function addChart(wb) {
  const sheet = wb.activeSheet;
  sheet.range('A1').values = [['Month', 'Revenue', 'Cost'], ['Jan', 120, 80], ['Feb', 135, 82], ['Mar', 150, 90]];
  const chart = sheet.chart(sheet.addChart('column', 'A1:C4', { x: 260, y: 10, w: 420, h: 260 }));
  chart.title = 'Revenue and cost, Q1';
  chart.altText = 'Column chart of revenue and cost for January to March';
}

export function Report() {
  return (
    <div style={{ height: 520 }}>
      <Sheet onReady={addChart} onObjectSelected={(e) => console.log('selected', e.object)} />
    </div>
  );
}

Vue

<script setup>
import { Sheet } from '@8sheets/vue';

function addChart(wb) {
  const sheet = wb.activeSheet;
  sheet.range('A1').values = [['Month', 'Revenue', 'Cost'], ['Jan', 120, 80], ['Feb', 135, 82], ['Mar', 150, 90]];
  const chart = sheet.chart(sheet.addChart('column', 'A1:C4', { x: 260, y: 10, w: 420, h: 260 }));
  chart.title = 'Revenue and cost, Q1';
  chart.altText = 'Column chart of revenue and cost for January to March';
}
</script>

<template>
  <Sheet style="height: 520px" @ready="addChart" @object-selected="(e) => console.log('selected', e.object)" />
</template>

Angular

import { Component } from '@angular/core';
import { SheetComponent, SheetsWorkbook } from '@8sheets/angular';

@Component({
  selector: 'app-report',
  imports: [SheetComponent],
  template: `<eight-sheet class="grid" (ready)="addChart($event)" />`,
  styles: `.grid { height: 520px; }`,
})
export class Report {
  addChart(wb: SheetsWorkbook) {
    const sheet = wb.activeSheet;
    sheet.range('A1').values = [['Month', 'Revenue', 'Cost'], ['Jan', 120, 80], ['Feb', 135, 82], ['Mar', 150, 90]];
    const chart = sheet.chart(sheet.addChart('column', 'A1:C4', { x: 260, y: 10, w: 420, h: 260 }));
    if (!chart) return;
    chart.title = 'Revenue and cost, Q1';
    chart.altText = 'Column chart of revenue and cost for January to March';
  }
}

Add

  • sheet.addChart(type, range, rect, { title }) adds a chart and returns its record. The type is a chart type such as column, bar, line, pie, doughnut, area, scatter or radar. The range may be on another sheet ('Data!A1:D13'), and a single cell takes the block of data around it. Positions and sizes are in points from the sheet's top-left corner.
  • sheet.addShape(kind, rect) adds a shape: a preset such as rect, roundRect or ellipse, or line and arrow.
  • sheet.addCustomShape(model, options) adds a shape whose outline comes from formulas that can read cells.

Wrap the record in a handle with sheet.chart(record) or sheet.shape(record).

Find

CallGives
sheet.chartHandlesHandles for the charts on the sheet, in drawing order
sheet.shapeHandlesHandles for the shapes, connectors, pictures and text boxes
sheet.chart(which)A chart by name (any case), by position among the charts, or from the record addChart returned; null when there is none
sheet.shape(which)The same for shapes, pictures and text boxes
sheet.charts, sheet.shapesThe raw records, as before

Charts from an opened file are found the same way, so a template's chart can be retitled by name: sheet.chart('Sales chart').title = 'Sales 2027'.

What every object has

MemberWhat it does
kindchart, chartEx (the newer chart types), shape, connector, picture, textbox or group
nameThe name the Selection Pane and the name box show; set it to rename
rect, setRect(rect)Position and size in points; setRect changes the fields you give
altTextWhat a screen reader says for the object; '' or null removes it
bringToFront(), sendToBack(), bringForward(), sendBackward()Drawing order
remove()Deletes the object
existsfalse once the object was removed, or after a load replaced the workbook

Charts

MemberWhat it does
typeThe type it was made as, such as column; a chart from a file gives its first plot's type
titleThe title's text, or null when the chart shows the automatic title or none. Set text to change it, null to take the title away, '' to go back to the automatic title
seriesThe series and the references they chart: { name, values, categories }, as the Select Data dialog shows them

Shapes

MemberWhat it does
shapeTypeThe preset, such as rect, ellipse or straightConnector1; null for a picture or a group
textThe text in the shape, paragraphs joined by line breaks; setting it keeps the first paragraph's alignment and font
fill#RRGGBB, none, or null when it follows the shape style or is a gradient or picture; set null to follow the style again

In the app

Users format charts on the Chart Design and Format tabs; see Charts and visuals. From your own button, wb.commands.execute('ui.insertChart', 'line') opens the Insert Chart dialog.

Limits

  • Handles cover position, name, alternative text, drawing order, a chart's title and series references, and a shape's text and fill. Series formatting, axes, data labels and other chart elements are set in the app, and charts in template files keep all of theirs.
  • series is read-only: change what a chart shows by changing its cells, or make a new chart for another range.
  • In Node, charts can be added, changed and saved, but a PDF from a headless workbook doesn't draw them.