Place shape and chart controls

Put shape fill, outline, and chart controls in your own toolbar, popover, or drawer in React or Vue.

Every field of the Format shape pane and the Chart pane is a slot and a part. A slot is a command with an enabled state and a value. A part is a ready control for one slot. You can place parts anywhere inside DocxEditor.Root: a toolbar, a popover, a drawer, or a pane of your own. The parts follow the selection and repaint when another control changes the object.

Add controls to your toolbar

Each part takes a variant. Use variant="compact" in a toolbar: the label is for screen readers only, and the disabled reason shows in the tooltip. The default variant="field" shows a visible label and the disabled reason under the control. Inside DocxEditor.Toolbar, parts default to compact. Each part carries the editor's style scope, so it is styled wherever you place it, in light and dark mode.

The following toolbar adds the fill color and the outline dash of the selected shape:

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

function ShapeToolbar() {
  return (
    <div role="toolbar" aria-label="Shape">
      <DocxEditor.ShapeFill variant="compact" />
      <DocxEditor.ShapeOutlineDash variant="compact" />
    </div>
  );
}

When no shape is selected, the parts are disabled and give the reason.

Each part is also a named export with the DocxEditor prefix, such as DocxEditorShapeFill or DocxEditorChartTitle.

Customize a part in the toolbar

A part placed in DocxEditor.Toolbar replaces its slot in the default arrangement. The color parts and the toggle parts also take icon and asChild. The following toolbar changes the fill control, puts your own button on the data labels toggle, and removes the outline dash:

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

function EditorToolbar() {
  return (
    <DocxEditor.Toolbar>
      <DocxEditor.ShapeFill className="my-fill" icon={<FillIcon />} />
      <DocxEditor.ChartDataLabels asChild>
        <button type="button" className="my-toggle">
          Labels
        </button>
      </DocxEditor.ChartDataLabels>
      <DocxEditor.ShapeOutlineDash hidden />
    </DocxEditor.Toolbar>
  );
}

With preset={false}, the toolbar renders only the parts you place.

Use a slot without a part

To render your own control, read the slot with useObjectControl, as you read a value slot with useEditorValueCommand. It returns these members:

  • value is typed for the slot, such as a number for shape.outlineWidth. It is null when nothing is selected or the object shows several values. A color slot reads a grid pick or none, so you can pass it to ColorPicker.Root. ObjectSlotReadValueMap holds the types.
  • options lists the values of a list slot, such as the legend positions.
  • isEnabled, disabledReason, isActive, and label describe the control.
  • execute(value, options?) runs the slot and returns an ExecResult.
  • toggle(options?) turns a toggle slot on or off. Only chart.dataLabels, chart.axes, and chart.gridlines have it.
import { useObjectControl } from '@docx-editor.dev/react';

function LegendButtons() {
  const legend = useObjectControl('chart.legend');
  return (
    <div role="group" aria-label={legend.label}>
      {legend.options.map((position) => (
        <button
          key={position}
          type="button"
          disabled={!legend.isEnabled}
          aria-pressed={legend.value === position}
          onMouseDown={(event) => event.preventDefault()}
          onClick={() => legend.execute(position)}
        >
          {position}
        </button>
      ))}
    </div>
  );
}

The mouse handler keeps the editor selection when you press a button.

Outside React, run a slot with runToolbarCommand, and read its state with toolbarCommandState:

import { runToolbarCommand } from '@docx-editor.dev/core/editor';

const result = runToolbarCommand(editor, 'shape.outlineDash', 'dash');
if (!result.ok) console.warn(result.reason);

Show pane sections in a popover

Insert > Chart, Edit chart, and Format shape send a pane request. Any UI can answer it. usePaneRequest calls your listener for the panes that panes names. DocxEditor.PaneSections renders the sections of a pane, each a heading over its parts.

The following popover answers the chart request with the type and elements sections:

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

function ChartPopover() {
  const [open, setOpen] = useState(false);
  usePaneRequest(() => setOpen(true), { panes: ['chart'] });
  if (!open) return null;
  return (
    <div role="dialog" aria-label="Chart">
      <DocxEditor.PaneSections pane="chart" sections={['type', 'elements']} />
      <button type="button" onClick={() => setOpen(false)}>
        Close
      </button>
    </div>
  );
}

sections takes the section ids of the pane, so a typo or a section of another pane is a type error. PANE_SECTIONS lists the sections and their slots:

PaneSectionSlots
shapefillshape.fill, shape.fillTransparency
shapeoutlineshape.outlineColor, shape.outlineWidth, shape.outlineDash
charttypechart.type
chartelementschart.title, chart.legend, chart.dataLabels, chart.axes, chart.gridlines, chart.categoryAxisTitle, chart.valueAxisTitle
chartcolorschart.seriesColor
chartdatachart.data

Build a pane from parts

Combine sections and single parts into your own pane or drawer. A part for an element that the chart type does not have renders nothing. For example, DocxEditor.ChartAxes renders nothing for a pie chart.

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

function ChartDrawer() {
  return (
    <aside aria-label="Chart">
      <DocxEditor.ChartType />
      <DocxEditor.ChartTitle />
      <DocxEditor.ChartLegend />
      <DocxEditor.ChartDataLabels />
      <DocxEditor.ChartAxes />
      <DocxEditor.ChartGridlines />
      <DocxEditor.ChartCategoryAxisTitle />
      <DocxEditor.ChartValueAxisTitle />
      {/* index shows one series; omit it to show every series */}
      <DocxEditor.ChartSeriesColors index={0} />
      <DocxEditor.ChartData />
    </aside>
  );
}

To insert a chart from your own UI, place DocxEditor.ChartInsert. It is the chart type list of the insert.chart slot, with Trigger, Content, and Item parts.

Use the color picker

The fill, outline, and series color parts use the ColorPicker compound. You can use it for your own color controls. It has these parts:

  • ColorPicker.Root holds the value and the open state, and calls onPick.
  • ColorPicker.Trigger opens the grid.
  • ColorPicker.Content is the grid: No color, theme colors with tints and shades, standard colors, and a hex field.
  • ColorPicker.Swatch, ColorPicker.NoColor, and ColorPicker.HexInput are the parts of the grid.

A theme pick such as accent1:40 saves as a theme color reference on shapes and charts. On a table border or shading, it saves as an RGB value. The following control sets the shape outline color:

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

function OutlineColor() {
  const outline = useObjectControl('shape.outlineColor');
  return (
    <DocxEditor.ColorPicker.Root
      value={outline.value}
      disabled={!outline.isEnabled}
      onPick={(pick) => outline.execute(pick)}
    >
      <DocxEditor.ColorPicker.Trigger aria-label={outline.label} />
      <DocxEditor.ColorPicker.Content />
    </DocxEditor.ColorPicker.Root>
  );
}

To build your own grid, put ColorPicker.NoColor, ColorPicker.Swatch with a pick, and ColorPicker.HexInput inside ColorPicker.Content.

To place the grid with a popover library, pass a ref to ColorPicker.Trigger and render ColorPicker.Content in your floating element with container. The grid then renders there through a portal, keeps the editor's style scope, and takes no position of its own:

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

function FloatingFill({ floating }: { floating: HTMLElement | null }) {
  const [anchor, setAnchor] = useState<HTMLButtonElement | null>(null);
  return (
    <DocxEditor.ColorPicker.Root value="accent1" onPick={(pick) => console.log(pick)}>
      <DocxEditor.ColorPicker.Trigger ref={setAnchor} aria-label="Fill" />
      {/* Position `floating` next to `anchor` with your popover library. */}
      <DocxEditor.ColorPicker.Content container={floating} />
    </DocxEditor.ColorPicker.Root>
  );
}

Use the controls in Vue

Vue exposes the same parts on the DocxEditor namespace, and the same useObjectControl and usePaneRequest composables. The composables return refs.

<script setup lang="ts">
import { ref } from 'vue';
import { DocxEditor, usePaneRequest } from '@docx-editor.dev/vue';

const open = ref(false);
usePaneRequest(() => (open.value = true), { panes: ['chart'] });
</script>

<template>
  <div role="toolbar" aria-label="Shape">
    <DocxEditor.ShapeFill variant="compact" />
    <DocxEditor.ShapeOutlineDash variant="compact" />
  </div>
  <div v-if="open" role="dialog" aria-label="Chart">
    <DocxEditor.PaneSections pane="chart" :sections="['type', 'elements']" />
  </div>
</template>

The following color control reads the outline color and passes it to ColorPicker.Root:

<script setup lang="ts">
import { DocxEditor, useObjectControl, type ColorPick } from '@docx-editor.dev/vue';

const { value, isEnabled, label, execute } = useObjectControl('shape.outlineColor');
const pick = (color: ColorPick | 'none') => execute(color);
</script>

<template>
  <DocxEditor.ColorPicker.Root :value="value" :disabled="!isEnabled" @pick="pick">
    <DocxEditor.ColorPicker.Trigger :aria-label="label" />
    <DocxEditor.ColorPicker.Content />
  </DocxEditor.ColorPicker.Root>
</template>

Slot reference

runToolbarCommand and execute take these values. ObjectSlotValueMap holds the same types.

SlotValue
shape.fillA color pick (accent1:40, #4472C4), or none for No fill
shape.fillTransparencyA whole percent from 0 (opaque) to 100 (clear)
shape.outlineColorA color pick, or none for No line
shape.outlineWidthPoints, from 0.25 to 1584
shape.outlineDashA ShapeOutlineDash preset, such as solid, sysDot, dash, or lgDashDotDot
chart.typeA ChartType, such as columnClustered, line, or pie
chart.titleThe title text; empty text or null removes the title
chart.legendA ChartLegendPosition, such as right, bottom, or none
chart.dataLabelstrue or false; with no value, the slot toggles
chart.axestrue or false; with no value, the slot toggles
chart.gridlinestrue or false; with no value, the slot toggles
chart.categoryAxisTitleThe axis title; empty text or null removes it
chart.valueAxisTitleThe axis title; empty text or null removes it
chart.seriesColor{ index, color }, where color is a color pick or auto
chart.dataOne ChartPaneChange, or the whole data without workbook

The outline dash list offers eight presets: solid, sysDot, sysDash, dash, dashDot, lgDash, lgDashDot, and lgDashDotDot. The command accepts all 11 ST_PresetLineDashVal values. The dash saves as a:prstDash, and as v:stroke/@dashstyle on VML shapes.

Note these facts about the slots:

  • The default toolbar adds the shape group when you select a shape, and the chart group when you select a chart. Each group shows only its compact controls; the other slots stay in the panes. For the full table, see Chrome slot reference.
  • Diagrams use the image.* slots of the image group. They have no slots of their own.
  • The chart color helpers, such as chartColorGrid and chartColorLabel, stay as deprecated aliases of the color picker names.