# Managing drawings (/vela-pro/charts/drawings/editing)



Drawings remain interactive after placement in both the chart UI and the programmatic API. User gestures and `chart.drawings` calls operate on the same underlying model in Vela's open-source core (`@luxalgo/vela`), where every drawing is represented as plain JSON containing its tool type, time-and-price anchor points, and visual style.

## Interactive editing [#interactive-editing]

### Selection and styling [#selection-and-styling]

Clicking a drawing selects it, reveals its anchor handles, and opens a floating toolbar with the style controls supported by that tool (line color, width, dash style, fill color, and text formatting). The floating toolbar also includes lock and delete buttons, plus a `⋮` overflow menu to duplicate the drawing in place, bring it to the front, send it to the back, or reset its settings.

Clicking the gear icon on the floating toolbar (or double-clicking the drawing) opens the full settings dialog. Depending on the tool type, the dialog exposes visual styles, tool-specific parameters (such as Fibonacci retracement levels or position sizing), text labels, exact price-and-time coordinates for each anchor point, and per-timeframe visibility rules. Clicking **Cancel** or pressing `Escape` reverts changes made while the dialog was open.

Drag an anchor handle to reshape a drawing, or drag its body to move the entire drawing across time and price.

### Multi-selection and duplication [#multi-selection-and-duplication]

* `Shift`+click or `Ctrl/Cmd`+click a drawing to add it to or remove it from the active selection.
* `Ctrl/Cmd`+drag across empty chart space to marquee-select multiple drawings.
* Drag the body of any selected item to move the entire selection together while locked drawings remain fixed in place.
* A single floating toolbar controls the multi-selection and displays the controls shared across all selected tools. Any property whose value differs across the selected drawings displays a mixed state.

Style edits, moves, deletions, and duplications performed on a multi-selection are recorded together as a single undo step.

To duplicate by dragging, hold `Ctrl/Cmd` and drag a drawing's body to pull a copy away while leaving the original in place. Releasing the pointer commits the duplicate, while pressing `Escape` mid-drag cancels the copy. When multiple drawings are selected, `Ctrl/Cmd`+drag duplicates the entire selection at once.

### Z-order and stacking [#z-order-and-stacking]

Newly placed drawings default to a layer beneath the price series so candlesticks and bars remain legible over shaded zones and bands. From there, a drawing can be moved to any position in its pane's render stack, including above all series, between two indicators, or behind every other element.

Users can reorder drawings in the Object Tree, which lists each pane's drawings, indicators, and price series from front to back. Dragging a row moves the drawing to a specific slot, and right-clicking a row provides **Bring to front** and **Send to back** actions. Stacking order is persisted with the drawing record. See [Depth anywhere in the stack](/vela/user/drawing-tools#depth-anywhere-in-the-stack) in the core docs for the underlying z-order rules.

### Keyboard and mouse shortcuts [#keyboard-and-mouse-shortcuts]

Keyboard shortcuts act on the active selection while the chart has focus (`Delete` and `Backspace` also remove a hovered drawing when nothing is selected) and yield whenever a text input has focus. Mouse shortcuts and `Alt` tool chords work without an active selection.

| Action                                      | Shortcut                                 |
| ------------------------------------------- | ---------------------------------------- |
| Undo                                        | `Ctrl/Cmd+Z`                             |
| Redo                                        | `Ctrl/Cmd+Shift+Z` or `Ctrl/Cmd+Y`       |
| Copy, paste, duplicate                      | `Ctrl/Cmd+C`, `Ctrl/Cmd+V`, `Ctrl/Cmd+D` |
| Delete                                      | `Delete` or `Backspace`                  |
| Nudge by 1 px, or by 10 px                  | Arrow keys, or `Shift`+arrow keys        |
| Cancel placement or clear selection         | `Escape`                                 |
| Delete hovered drawing                      | Middle-click                             |
| Cancel armed tool                           | Right-click                              |
| Arm Trend Line tool                         | `Alt+T`                                  |
| Place horizontal or vertical line at cursor | `Alt+H`, `Alt+V`                         |

Undo and redo (via keyboard shortcuts or topbar buttons) step through a single chronological history per chart covering both drawing edits and indicator additions or removals. See the core's [keyboard shortcuts reference](/vela/user/drawing-tools#keyboard-shortcuts) for the full shortcut table, and [Keyboard shortcuts](/vela-pro/customization/shortcuts) for workspace keymap configuration.

## Programmatic API [#programmatic-api]

Every chart instance exposes a `chart.drawings` controller. Resolve the target chart at the point of use via `workspace.chart` for the active chart, or `workspace.cell(id)?.chart` for a specific cell in a multi-chart layout.

```ts
import { VelaWorkspace } from '@luxalgo/vela/workspace';
import { BinanceProvider } from '@luxalgo/vela/providers/binance';
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro();

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    timeframe: '60',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: true,
});

const chart = workspace.chart;
await chart.ready();

// Add a computed price level. Anchor points use { time (epoch ms), price }.
const level = chart.drawings.add('hline', {
    anchors: [{ time: Date.now(), price: 64000 }],
    style: { lineColor: '#e02424', lineWidth: 1 },
    text: { value: 'Desk resistance', size: 'small', hAlign: 'right', vAlign: 'top' },
});

// Read all drawings on the chart as plain JSON in paint order.
const levels = chart.drawings.all().filter((d) => d.type === 'hline');
console.log(levels.map((d) => d.anchors[0]?.price));

if (level) {
    // Update with a partial record. Each call records one undo step.
    chart.drawings.update(level.id, { anchors: [{ time: Date.now(), price: 65250 }] });
    chart.drawings.update(level.id, { style: { ...level.style, lineColor: '#f59e0b' } });
    chart.drawings.lock(level.id);

    // Remove the drawing. Locking blocks user gestures without blocking API calls.
    chart.drawings.remove(level.id);
}
```

`add()` returns the created drawing object, or `null` if the active renderer does not support drawings. It accepts any type key from the core's [tool catalogue](/vela/user/drawing-tools#tool-catalogue) along with an optional seed containing `paneId`, `anchors`, `style`, `text`, `props`, and `zIndex`. Although `update()` merges partial `style` fields at runtime, its TypeScript signature expects the complete `style` object, so spread `level.style` when modifying individual style properties.

`chart.drawings` also exposes methods for selection, visibility toggling, z-order adjustments (`bringToFront`, `sendToBack`), duplication, clipboard copy and paste, and undo/redo history. See the core's [`chart.drawings` API reference](/vela/user/api-reference#chartdrawings--the-drawings-control-surface) for the complete method list.

<Warning>
  Drawings created with `chart.drawings.add()` are persisted alongside user-created drawings. Calling `add()` unconditionally on every page load will append a new copy on each reload. Because drawing records do not include a separate owner field, store the IDs of programmatically created drawings and check `chart.drawings.all()` before inserting them again.
</Warning>

### Subscribing to drawing events [#subscribing-to-drawing-events]

Use `chart.on(event, listener)` to observe drawing changes. Each call returns an unsubscribe callback:

```ts
import type { VelaWorkspace } from '@luxalgo/vela/workspace';

declare const workspace: VelaWorkspace;
declare function renderList(rows: { id: string; type: string; locked: boolean }[]): void;

const chart = workspace.chart;
const refresh = (): void => renderList(chart.drawings.all());

const events = ['drawing:created', 'drawing:edited', 'drawing:removed', 'drawing:history', 'drawing:replaced'] as const;
const offs = events.map((event) => chart.on(event, refresh));

chart.on('drawing:selected', ({ ids }) => console.log(`${ids.length} selected`));

// Unsubscribe when your component unmounts.
const stop = (): void => offs.forEach((off) => off());
```

| Event              | Payload       | When it fires                                                                                                                |
| ------------------ | ------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `drawing:created`  | `{ id }`      | A drawing is placed interactively, added via code, pasted, or duplicated.                                                    |
| `drawing:edited`   | `{ id }`      | A drawing's anchors, style, text, lock state, visibility, or z-order changes.                                                |
| `drawing:removed`  | `{ id }`      | A drawing is deleted.                                                                                                        |
| `drawing:selected` | `{ id, ids }` | Selection changes. `ids` contains all selected drawing IDs, and `id` is the first ID or `null`.                              |
| `drawing:history`  | `{ action }`  | An undo or redo step runs. Item-level `created`, `edited`, and `removed` events do not fire during history traversal.        |
| `drawing:replaced` | `{ cause }`   | The chart's drawing set is replaced as a unit because a state document loaded (`'load'`) or the symbol changed (`'symbol'`). |

Any external UI that mirrors the chart's drawing list should listen to `drawing:history` and `drawing:replaced` in addition to the item-level events and re-read `chart.drawings.all()` whenever either fires.

## Tool defaults and saved styles [#tool-defaults-and-saved-styles]

Each tool remembers the visual settings applied to its most recently styled drawing, including colors, line widths, text formatting (excluding the text content itself), and tool-specific properties such as Fibonacci levels. Subsequent drawings of that tool type inherit those settings automatically. Users can also save named style presets from the settings dialog's header menu and apply them to any drawing of the same type. Line tools include built-in **Support**, **Resistance**, and **Projection** presets, while area tools include **Demand** and **Supply** presets.

Both tool defaults and saved style templates apply workspace-wide, persist in the workspace state document, and serialize as plain JSON keyed by tool type:

```ts
import type { VelaWorkspace } from '@luxalgo/vela/workspace';

declare const workspace: VelaWorkspace;

const drawings = workspace.chart.drawings;

// Configure the default appearance for newly drawn rectangles.
drawings.setToolDefaults({
    ...drawings.toolDefaults(),
    box: { style: { lineColor: '#2563eb', fillColor: '#2563eb26' }, text: { size: 'small' } },
});
drawings.resetToolDefaults('trendline'); // restore factory defaults for trendline

// Register a named preset in the rectangle tool's style menu alongside user-saved presets.
const saved = drawings.toolTemplates();
const own = (saved.box ?? []).filter((style) => style.name !== 'Desk demand');
drawings.setToolTemplates({
    ...saved,
    box: [...own, { name: 'Desk demand', settings: { style: { lineColor: '#0e9f6e', fillColor: '#0e9f6e26' } } }],
});

workspace.chart.on('drawing:defaults', ({ type }) => console.log('defaults changed for', type));
workspace.chart.on('drawing:templates', ({ type }) => console.log('styles changed for', type));
```

Because `setToolDefaults()` and `setToolTemplates()` replace the entire map for all tools, spread the current values returned by `toolDefaults()` or `toolTemplates()` when updating an individual tool.

<Note>
  Adding or updating a drawing via `chart.drawings` updates that tool's last-used defaults in the same way an interactive edit does. For example, after running the `hline` update earlier on this page, the next horizontal line drawn by the user starts in amber (`#f59e0b`). To avoid altering user defaults during programmatic updates, read `drawings.toolDefaults()` beforehand and restore it with `drawings.setToolDefaults()` afterward.
</Note>

## Multi-chart sync and per-symbol storage [#multi-chart-sync-and-per-symbol-storage]

In a multi-chart grid, enabling **Sync drawings on all charts** on the toolbar copies each newly placed drawing onto linked charts at matching time and price coordinates. Synced copies remain linked while sync is enabled, so moving, restyling, or deleting one updates the others automatically. You can toggle drawing sync from code with `workspace.sync.set('drawings', true)` or via the workspace `sync` constructor option. Link pairings are not stored separately; when a saved workspace reloads with drawing sync active, identical drawings on linked charts are re-linked automatically. See [Sync links](/vela/user/workspace#sync-links) in the core docs for details on chart sync groups.

Vela Pro stores drawings per symbol automatically. Switching a chart's symbol unloads the previous symbol's drawings and restores any drawings saved for the new symbol. When multi-chart sync copies a drawing across charts, each copy belongs to the symbol displayed on its respective chart. See [Drawing persistence](/vela-pro/persistence/stores/drawings) for local and server-side storage configuration.

## Related [#related]

* [Drawing tools](/vela-pro/charts/drawings/tools)
* [Custom drawing tools](/vela-pro/charts/drawings/custom-tools)
* [Drawing persistence](/vela-pro/persistence/stores/drawings)
* [Drawings API reference](/vela-pro/api/drawings)
