- Spreadsheet docs
- 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 ascolumn,bar,line,pie,doughnut,area,scatterorradar. 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 asrect,roundRectorellipse, orlineandarrow.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
| Call | Gives |
|---|---|
sheet.chartHandles | Handles for the charts on the sheet, in drawing order |
sheet.shapeHandles | Handles 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.shapes | The 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
| Member | What it does |
|---|---|
kind | chart, chartEx (the newer chart types), shape, connector, picture, textbox or group |
name | The 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 |
altText | What a screen reader says for the object; '' or null removes it |
bringToFront(), sendToBack(), bringForward(), sendBackward() | Drawing order |
remove() | Deletes the object |
exists | false once the object was removed, or after a load replaced the workbook |
Charts
| Member | What it does |
|---|---|
type | The type it was made as, such as column; a chart from a file gives its first plot's type |
title | The 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 |
series | The series and the references they chart: { name, values, categories }, as the Select Data dialog shows them |
Shapes
| Member | What it does |
|---|---|
shapeType | The preset, such as rect, ellipse or straightConnector1; null for a picture or a group |
text | The 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.
seriesis 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.