Charts

Insert charts at the caret, then edit their type, elements, colors, and data. Each change is one undo step.

The @docx-editor.dev/pro/drawing module paints charts and requires the EigenPal Pro License. Without it, chart insertion and editing remain available, but charts show placeholders.

Insert a chart

Run insertChart with a chart type. The editor inserts the chart inline at the caret, fills it with sample data, and selects it:

editor.exec({ type: 'insertChart', chartType: 'columnClustered' });

// Your own data, three categories and two series.
editor.exec({
  type: 'insertChart',
  chartType: 'line',
  data: {
    categories: ['North', 'South', 'East'],
    series: [
      { name: 'Plan', values: [3, 5, 4] },
      { name: 'Actual', values: [2, 6, null] },
    ],
  },
});

Use Insert > Chart or DocxEditor.Toolbar.ChartInsert for column, bar, line, area, pie, doughnut, and scatter charts. The command also accepts stacked, percent-stacked, marker, radar, and scatter-with-lines types.

Edit a chart

Each edit applies to the selected chart, or to the chart drawing that drawingNodeId names:

Read the current values with the chartData and chartFormat queries:

const read = editor.query({ type: 'chartData' });
if (read.ok) {
  editor.exec({
    type: 'setChartData',
    data: {
      kind: read.data.kind,
      categories: [...read.data.categories, { label: 'West' }],
      series: read.data.series.map((s) => ({ ...s, values: [...s.values, 7] })),
    },
  });
}

editor.exec({ type: 'setChartFormat', format: { title: 'Sales', legend: 'right' } });
editor.exec({ type: 'setChartColor', index: 0, color: { theme: 'accent2', shift: 40 } });

Use #RRGGBB, a theme color such as { theme: 'accent1' }, or null for automatic color. Positive shift values lighten the theme color by that percentage; negative values darken it.

A refused edit returns reason, which can contain a translation key such as chart.errors.noAxes. Use localizeDisabledReason from @docx-editor.dev/i18n to display it. The editor refuses chart edits in suggesting mode and in a document open for viewing.

Resize, move, and wrap a chart

Select a chart to resize it, change its wrapping, or set alternative text. Drag an inline chart onto editable text to move it, as you move an inline image. For free movement, change In Line with Text to another wrapping mode, then drag. Dropping a floating chart onto another body paragraph on the same page moves its anchor there. Locked anchors and positions relative to lines or characters keep their paragraph.

The drawing operations resizeDrawing, positionDrawing, setDrawingWrap, and setDrawingMetadata support chart frames. Crop, replace, and rotate are unsupported. Charts with alternate pictures also refuse frame edits because both representations must stay aligned.

Copy and paste a chart

Select a chart, then use Copy or Cut in its context menu. Keyboard shortcuts also work. Pasting replaces selected text and selects an independent chart copy with its own parts and embedded workbook.

The copy, cut, and paste commands provide the same behavior. Chart clipboard data works only between editors on the same browser page. Copying a chart together with other content is unsupported. Chart paste refuses in viewing and suggesting modes.

Show the Chart pane

The Chart pane shows the type, elements, colors, and data of the selected chart. Fields apply when you press Enter or leave them, and Escape restores the old value.

DocxEditor.SidePanel holds the pane. Insert > Chart asks the host to show the panel without moving the focus. Edit chart and a double-click on a chart move the focus into it. Listen for these requests with usePaneRequest:

import { useState } from 'react';
import { DocxEditor, usePaneRequest } from '@docx-editor.dev/react';

function ChartSidePanel() {
  const [open, setOpen] = useState(false);
  usePaneRequest((request) => {
    if (request.pane === 'chart') setOpen(true);
  });
  return open ? <DocxEditor.SidePanel onClose={() => setOpen(false)} /> : null;
}

Render this component inside DocxEditor.Root, beside DocxEditor.Viewport. Mount a side panel, Chart pane, or usePaneRequest listener to enable the Edit chart action. Vue uses DocxEditorSidePanel and the usePaneRequest composable. Use DocxEditor.ChartPane to place the pane in your own layout.

Build your own chart pane

Build your component with useSelectedChart, then pass it as children to DocxEditor.SidePanel. The hook returns the selected chart, its data and format, and editing availability with disabled reasons. Use these methods to edit that chart:

• execute takes the chart commands of editor.exec, without drawingNodeId.
• editData applies one checked data change, as the packaged pane does. Text that is not a number for a value refuses with a reason.

The following sample changes the chart type and displays refused edits:

import { useState } from 'react';
import { localizeDisabledReason } from '@docx-editor.dev/i18n';
import {
  CHART_TYPE_CHOICES,
  DocxEditor,
  chartTypeLabelKey,
  useSelectedChart,
  useTranslation,
  type ChartType,
} from '@docx-editor.dev/react';

function MyChartPane() {
  const { t } = useTranslation();
  const chart = useSelectedChart();
  const [error, setError] = useState<string | null>(null);
  if (!chart.chart || !chart.format) return <p>Select a chart.</p>;
  return (
    <>
      <select
        aria-label="Chart type"
        value={chart.format.type ?? ''}
        disabled={!chart.canEditFormat}
        title={chart.formatDisabledReason ?? undefined}
        onChange={(event) => {
          const result = chart.execute({
            type: 'setChartType',
            chartType: event.target.value as ChartType,
          });
          setError(result.ok ? null : localizeDisabledReason(result.reason, t));
        }}
      >
        <option value="" disabled>
          Unsupported chart type
        </option>
        {CHART_TYPE_CHOICES.map((type) => (
          <option key={type} value={type}>
            {t(chartTypeLabelKey(type))}
          </option>
        ))}
      </select>
      {error && <p role="alert">{error}</p>}
    </>
  );
}

<DocxEditor.SidePanel>
  <MyChartPane />
</DocxEditor.SidePanel>;

format.type is null for a chart type that the editor does not write. Each edit is one undo step. A refusal returns { ok: false, code, reason }, as editor.exec does. The disabled reasons are translated, and viewing and suggesting turn the edits off. Edit chart and double-click move focus to your pane's first field.

In Vue, useSelectedChart returns the same fields as computed refs, and you pass the pane in the default slot of DocxEditorSidePanel. Both adapters export the chart types, CHART_TYPE_CHOICES, and chartTypeLabelKey.

Limits

• Content locks and data bindings prevent chart data and formatting edits. Removal-only locks still allow these edits.

• The editor edits the data of charts with one plot and one level of categories. Other charts keep their data, and the pane says why.

• Data edits update chart values and supported embedded workbooks. Unsupported workbooks retain their bytes; inspect data.workbook before editing. External workbook links stop updating after data edits.

• Charts insert inline. Collaboration peers receive chart inserts, edits, resizes, and moves.