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:
valueis typed for the slot, such as a number forshape.outlineWidth. It isnullwhen nothing is selected or the object shows several values. A color slot reads a grid pick ornone, so you can pass it toColorPicker.Root.ObjectSlotReadValueMapholds the types.optionslists the values of a list slot, such as the legend positions.isEnabled,disabledReason,isActive, andlabeldescribe the control.execute(value, options?)runs the slot and returns anExecResult.toggle(options?)turns a toggle slot on or off. Onlychart.dataLabels,chart.axes, andchart.gridlineshave 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:
| Pane | Section | Slots |
|---|---|---|
shape | fill | shape.fill, shape.fillTransparency |
shape | outline | shape.outlineColor, shape.outlineWidth, shape.outlineDash |
chart | type | chart.type |
chart | elements | chart.title, chart.legend, chart.dataLabels, chart.axes, chart.gridlines, chart.categoryAxisTitle, chart.valueAxisTitle |
chart | colors | chart.seriesColor |
chart | data | chart.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.Rootholds the value and the open state, and callsonPick.ColorPicker.Triggeropens the grid.ColorPicker.Contentis the grid: No color, theme colors with tints and shades, standard colors, and a hex field.ColorPicker.Swatch,ColorPicker.NoColor, andColorPicker.HexInputare 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.
| Slot | Value |
|---|---|
shape.fill | A color pick (accent1:40, #4472C4), or none for No fill |
shape.fillTransparency | A whole percent from 0 (opaque) to 100 (clear) |
shape.outlineColor | A color pick, or none for No line |
shape.outlineWidth | Points, from 0.25 to 1584 |
shape.outlineDash | A ShapeOutlineDash preset, such as solid, sysDot, dash, or lgDashDotDot |
chart.type | A ChartType, such as columnClustered, line, or pie |
chart.title | The title text; empty text or null removes the title |
chart.legend | A ChartLegendPosition, such as right, bottom, or none |
chart.dataLabels | true or false; with no value, the slot toggles |
chart.axes | true or false; with no value, the slot toggles |
chart.gridlines | true or false; with no value, the slot toggles |
chart.categoryAxisTitle | The axis title; empty text or null removes it |
chart.valueAxisTitle | The axis title; empty text or null removes it |
chart.seriesColor | { index, color }, where color is a color pick or auto |
chart.data | One 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
chartColorGridandchartColorLabel, stay as deprecated aliases of the color picker names.