# Drawing tools (/vela-pro/charts/drawings/tools)



Every workspace created after calling `enableVelaPro()` includes a drawing toolbar docked along the left edge of the chart. The toolbar organizes 79 interactive tools into seven groups and adds searchable dropdown menus, starred favorites, and a radial tool wheel triggered by holding a single key. Interactive drawings are implemented in Vela's open-source core (`@luxalgo/vela`), while Vela Pro provides the enhanced menu UI, hover description cards, and radial wheel around them.

All drawing features are enabled by default. The following example restricts the toolbar to a curated subset of tools and customizes both the searchable menus and the radial wheel:

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

enableVelaPro({
    drawingMenus: { searchFrom: 5, descriptions: { 'Trend Line': 'Connect two swing points to mark a trend.' } },
    radialWheel: { fallbackTools: ['trendline', 'hline', 'box', 'fibretracement'], timeframes: ['5', '15', '60', '240', 'D'] },
});

const workspace = new VelaWorkspace('#chart', {
    layout: false,
    symbol: 'BTCUSDT',
    timeframe: '60',
    live: true,
    providers: { binance: () => new BinanceProvider() },
    persist: true,
    drawings: { tools: ['trendline', 'hline', 'ray', 'box', 'text', 'fibretracement', 'position'] },
});
```

`drawings` is a core `VelaWorkspace` option that controls which tools appear on the toolbar. `drawingMenus` and `radialWheel` are Vela Pro options passed to `enableVelaPro()` before constructing the workspace.

## Drawing toolbar [#drawing-toolbar]

A single toolbar serves the entire workspace and targets whichever chart cell is currently active. From top to bottom, it contains the **Cursor** button (which returns to selection mode), the seven tool group buttons, **Measure**, **Eraser**, **Magnet**, **Stay in drawing mode**, and **Sync drawings on all charts**, followed by a collapse toggle at the bottom. **Measure** activates a temporary price-and-time ruler that is never persisted, and **Eraser** deletes any drawings you click or drag across.

Each group button displays the icon of the most recently selected tool in that group. Clicking the button arms that tool immediately, while clicking the side arrow that appears on hover opens the group menu so the user can choose another tool. Once a tool is armed, clicking on the chart places its anchor points.

| Group        | Menu sections                           | Tools | Examples                                                                         |
| ------------ | --------------------------------------- | ----- | -------------------------------------------------------------------------------- |
| Lines        | Lines, Channels, Pitchforks             | 17    | Trend Line, Horizontal Line, Ray, Parallel Channel, Linear Regression, Pitchfork |
| Fibonacci    | Fibonacci, Price Action, Gann, Geometry | 23    | Fib Retracement, Fib Extension, Fair Value Gap, Order Block, Gann Fan            |
| Patterns     | Patterns, Elliott Waves, Harmonics      | 11    | XABCD Pattern, Head & Shoulders, Elliott Impulse Wave (1-5), Gartley             |
| Measurements | Measurements, Volume                    | 5     | Long/Short Position, Date & Price Range, Magnifier, Anchored VWAP                |
| Shapes       | Brushes, Arrows, Shapes                 | 14    | Brush, Highlighter, Arrow, Rectangle, Ellipse, Path                              |
| Text         | Text                                    | 7     | Text, Callout, Note, Price Label, Signpost                                       |
| Icons        | Icons                                   | 2     | Flag, Icon                                                                       |

The core's [tool catalogue](/vela/user/drawing-tools#tool-catalogue) documents each built-in tool and its string type key (used in `drawings.tools`, `radialWheel.fallbackTools`, and `chart.drawings`). Four toolbar tools are not yet listed in that reference table: Linear Regression (`regressionchannel`), Anchored VWAP (`anchoredvwap`), Fixed Range Volume Profile (`fixedrangevp`), and Highlighter (`highlighter`).

On mobile viewports, the desktop toolbar is replaced by a bottom sheet containing the same tool groups and favorites. See [Responsive layout](/vela-pro/customization/mobile/responsive) for mobile layout details.

## Drawing menus [#drawing-menus]

When `drawingMenus` is enabled, each tool group opens an enhanced menu designed for navigating large tool catalogues:

* **Search input:** Displayed on menus containing at least eight tools (configurable via `searchFrom`). Search matches both tool names and section titles, and typing while a menu is open routes keystrokes directly into the search input.
* **Section headers and counts:** Displays the tool count beside each section heading and the total number of matching tools in the menu footer.
* **Keyboard shortcut badges:** Displays keycap hints next to tools that have a registered shortcut.
* **Hover cards:** Shows a preview card with the tool's name and a one-line summary when hovering a row.

Menu rows remain standard toolbar buttons, so selecting a tool, starring a favorite, and triggering shortcuts work identically to the core menus. Vela Pro also upgrades the toolbar's own button tooltips into cards showing the tool icon, name, description, and (on group buttons) a reminder that the side arrow opens the full menu.

Hover cards and rich tooltips look up descriptions by the display name shown on the toolbar. Vela Pro includes built-in descriptions for 74 of the 79 tools; the five tools in the Geometry section do not ship with default descriptions. You can supply missing descriptions or override built-in copy through the `drawingMenus.descriptions` option, or register them at runtime with `registerDrawingToolDescription(name, text)`, which returns an unregister function that restores the previous text.

## Favorites [#favorites]

Every row in a tool menu has a star toggle on its right edge. Starring a tool adds it to a workspace-wide favorites list in the order starred, and the list is saved in the workspace state document when `persist` is enabled. Because favorites are managed by the core, you can read, initialize, and observe them programmatically through `chart.drawings`:

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

declare const workspace: VelaWorkspace;
declare function saveFavorites(types: string[]): void;

const drawings = workspace.chart.drawings;
if (drawings.favorites().length === 0) drawings.setFavorites(['trendline', 'hline', 'box', 'fibretracement']);

workspace.chart.on('drawing:favorites', ({ favorites }) => saveFavorites(favorites));
```

## Radial wheel [#radial-wheel]

Holding `Alt` for 200 ms while the workspace has focus opens the radial tool wheel centered over the workspace. Move the pointer toward a slice to highlight a tool and release `Alt` to arm it, or release `Alt` with the pointer inside the center hub to cancel without changing tools.

The wheel displays up to 11 starred favorites plus a **Cursor** slice fixed at the 6 o'clock position to return to selection mode. Until the user stars at least one favorite, the wheel populates from a default starter set consisting of Trend Line, Horizontal Line, Vertical Line, Ray, Rectangle, Brush, Text, Fib Retracement, and Parallel Channel.

While the wheel is open, the center hub displays "Click for timeframes". Clicking the hub switches the slices to timeframe presets (`1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1D`, `1W`, and `1M`, with a dot indicating the active chart's current timeframe). Aim at a timeframe and release `Alt` to switch the active chart. Clicking the hub again returns to the drawing tools, and subsequent opens always start on the tool ring.

A brief tap of `Alt` does not open the wheel, and pressing a key chord such as `Alt+T` cancels it immediately so keyboard shortcuts continue to work without interference. The wheel never opens when a text input has focus or while `Ctrl`, `Cmd`, or `Shift` is held, which is why those modifier keys cannot be configured as `triggerKey`.

<Note>
  The workspace `drawings` allowlist filters the toolbar only and does not change the radial wheel's default starter set. When restricting the toolbar with `drawings.tools` or `drawings.groups`, pass the matching tool keys to `radialWheel.fallbackTools` as well.
</Note>

## Magnet and stay in drawing mode [#magnet-and-stay-in-drawing-mode]

**Magnet** snaps newly placed anchor points to the nearest candle's open, high, low, or close price. It supports three modes: `'off'`, `'weak'` (snaps only when an OHLC value is within a few pixels of the pointer), and `'strong'` (always snaps to the nearest OHLC value). Holding `Ctrl` or `Cmd` while placing an anchor temporarily enforces strong snapping for that point.

**Stay in drawing mode** keeps the active tool armed after completing a drawing. When disabled, standard tools return to selection mode after a single placement, whereas brush tools remain armed regardless of this setting.

Both settings apply across every chart in the workspace and persist in the workspace state document. You can read, update, and subscribe to them from code:

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

declare const workspace: VelaWorkspace;

const chart = workspace.chart;
chart.drawings.setSnapMode('weak'); // 'off' | 'weak' | 'strong'
chart.drawings.setStayMode(true);

chart.on('drawing:snap', ({ mode }) => console.log('magnet', mode));
chart.on('drawing:stay', ({ on }) => console.log('stay in drawing mode', on));
```

## Customizing or hiding the toolbar [#customizing-or-hiding-the-toolbar]

The workspace `drawings` option accepts `false` or a configuration object:

* **`tools`:** Filters the toolbar to an allowlist of tool type keys while preserving the standard groups and menu sections.
* **`groups`:** Replaces the default toolbar layout with custom groups, each specified as `{ id, label, tools }`. Custom groups take precedence over `tools` and render flat menus without subsections.
* **`false`:** Removes the desktop toolbar and the mobile drawings sheet entry.

Passing `drawings: false` removes the toolbar UI without disabling the drawing subsystem itself. Programmatic calls through `chart.drawings` continue to work, as do the radial wheel and the `Alt+T`, `Alt+H`, and `Alt+V` shortcuts. To disable interactive drawing triggers completely, also pass `radialWheel: false` to `enableVelaPro()` and unregister the three default shortcut bindings (`drawings.trendline`, `drawings.hline-cursor`, and `drawings.vline-cursor`) via `workspace.keymap.unregister(id)`.

To hide only the toolbar while keeping the rest of the drawing configuration intact, pass `drawingToolbar: false` on the workspace instead.

## Options [#options]

`drawings` and `drawingToolbar` are `VelaWorkspace` constructor options. The remaining options are passed to `enableVelaPro()`, or to `enableDrawingMenus()` and `enableRadialWheel()` when enabling features individually.

| Option                      | Default      | Description                                                                                                                                                                   |
| --------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `drawings`                  | All tools    | Workspace option. Pass `false` to remove the toolbar and mobile entry, or pass `{ tools }` or `{ groups }` to customize toolbar contents.                                     |
| `drawingToolbar`            | `true`       | Workspace option. Pass `false` to hide the toolbar while keeping tools accessible via the radial wheel, shortcuts, and `chart.drawings`.                                      |
| `drawingMenus`              | Enabled      | Vela Pro option. Pass `false` to use the core's plain menus and tooltips.                                                                                                     |
| `drawingMenus.searchFrom`   | `8`          | Minimum number of tools in a menu before the search input appears. Pass `0` to disable search.                                                                                |
| `drawingMenus.cards`        | `true`       | Shows a description card when hovering a tool in a group menu.                                                                                                                |
| `drawingMenus.toolbarTips`  | `true`       | Upgrades toolbar button tooltips to description cards.                                                                                                                        |
| `drawingMenus.descriptions` | None         | Additional or replacement tool descriptions, keyed by the tool's toolbar display name.                                                                                        |
| `drawingMenus.decorate`     | None         | Custom menu decorator used instead of Vela Pro's built-in menu UI. Called with `(menuEl, hostEl)` each time a menu opens, and may return a cleanup callback invoked on close. |
| `radialWheel`               | Enabled      | Vela Pro option. Pass `false` to disable the radial tool wheel.                                                                                                               |
| `radialWheel.triggerKey`    | `'Alt'`      | Key held to open the wheel, specified as a `KeyboardEvent.key` value.                                                                                                         |
| `radialWheel.holdMs`        | `200`        | Hold duration in milliseconds required before the wheel opens.                                                                                                                |
| `radialWheel.fallbackTools` | Starter set  | Tool keys shown before the user stars any favorites. Pass `[]` to keep the wheel closed until at least one tool is starred.                                                   |
| `radialWheel.timeframes`    | `1m` to `1M` | Timeframes displayed in the secondary ring, ordered clockwise from 12 o'clock. Pass `[]` to disable timeframe switching and keep the hub as a cancel zone.                    |

## Related [#related]

* [Managing drawings](/vela-pro/charts/drawings/editing)
* [Custom drawing tools](/vela-pro/charts/drawings/custom-tools)
* [Drawing persistence](/vela-pro/persistence/stores/drawings)
* [Keyboard shortcuts](/vela-pro/customization/shortcuts)
* [Drawing tools (core)](/vela/user/drawing-tools)
