# Custom panels and widgets (/vela-pro/modules/extending/custom-widgets)



You can extend a Vela Pro workspace with custom side panels, bottom dock panels, and side rail action buttons using declarative registration descriptors. Vela Pro mounts your DOM elements into the shell layout and passes a live `WidgetContext` for reading chart state and dispatching workspace actions.

Follow two rules across every registration API on this page:

* **Register before constructing workspaces:** `VelaWorkspace` snapshots registered panels and actions during construction. If you register an action dynamically after construction, call `workspace.refreshActions()`.
* **Read workspace state from the `ctx` parameter:** `mount` and `run` callbacks execute per workspace instance and receive that workspace's `WidgetContext`. Read the active chart, symbol, and `host` element from `ctx` rather than closing over an outer workspace reference so descriptors support multiple workspaces on the same page.

## Writing a widget [#writing-a-widget]

Structure panel content using the same standalone widget pattern used by Vela Pro's built-in modules: a factory function accepting props and returning `{ el, update, destroy }`. Keeping data inputs in props and user actions in callbacks keeps the widget decoupled from `VelaWorkspace`, so the same component can mount inside a side panel, inside the bottom dock, or on a standalone page.

```ts
export interface ResearchProps {
    symbol?: string;
    /** Optional click handler. When omitted, notes render as static text. */
    onOpenNote?: (id: string) => void;
}

export function createResearch(props: ResearchProps = {}) {
    let current = { ...props };
    let request: AbortController | null = null;
    const el = document.createElement('div');
    el.className = 'acme-research';

    const load = async (): Promise<void> => {
        request?.abort();
        const { signal } = (request = new AbortController());
        if (!current.symbol) return;
        const res = await fetch(`/api/research/${encodeURIComponent(current.symbol)}`, { signal });
        const notes = (await res.json()) as Array<{ id: string; title: string }>;
        el.replaceChildren(
            ...notes.map((note) => {
                const row = document.createElement(current.onOpenNote ? 'button' : 'p');
                row.textContent = note.title;
                row.onclick = () => current.onOpenNote?.(note.id);
                return row;
            }),
        );
    };
    const refresh = (): void => void load().catch(() => {}); // ignore aborted fetches
    refresh();

    return {
        el,
        update(next: Partial<ResearchProps>): void {
            const moved = next.symbol !== undefined && next.symbol !== current.symbol;
            current = { ...current, ...next };
            if (moved) refresh();
        },
        destroy(): void {
            request?.abort();
            el.remove();
        },
    };
}
```

## Side panels [#side-panels]

`registerSidePanel` is exported by the plugin SDK in Vela's open-source core (`@luxalgo/vela/plugin`). The workspace renders the panel header, close button, and side rail toggle button, passing the body container to `mount`. Setting `placement: 'column'` docks the panel as a full-height column beside the chart area, matching Vela Pro's built-in side panels.

```ts
import { registerIcon, registerSidePanel } from '@luxalgo/vela/plugin';
import { describeRailEntry } from '@luxalgo/vela-pro';
import { onActiveSymbol } from '@luxalgo/vela-pro/plugin';

// Standalone widget defined in the section above.
declare function createResearch(props: { symbol?: string; onOpenNote?: (id: string) => void }): {
    el: HTMLElement;
    update(next: { symbol?: string }): void;
    destroy(): void;
};

export const RESEARCH_PANEL_ID = 'acme.research';

registerIcon('acme-research', '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor"><path d="M4 2.5h8v11H4zM6 6h4M6 9h4"/></svg>');
describeRailEntry(RESEARCH_PANEL_ID, { description: 'Analyst notes for the symbol on the chart.' });

registerSidePanel({
    id: RESEARCH_PANEL_ID,
    title: 'Research',
    icon: 'acme-research',
    placement: 'column',
    order: 6, // place after Vela Pro's built-in panels (orders 0 through 5)
    width: 360,
    resizable: true,
    minWidth: 280,
    maxWidth: 560,
    mount: (ctx, body) => {
        const research = createResearch({
            symbol: ctx.symbol,
            onOpenNote: (id) => window.open(`/research/notes/${encodeURIComponent(id)}`),
        });
        body.append(research.el);
        // Fires immediately and whenever the active chart cell or its symbol changes.
        const offSymbol = onActiveSymbol(ctx, (symbol) => research.update({ symbol }));
        return {
            destroy: () => {
                offSymbol();
                research.destroy();
            },
        };
    },
});
```

Registered side panels automatically appear on the side rail sorted by `order`. Calling `describeRailEntry` attaches hover-card description text to the rail button. To open or close the panel programmatically, call `ctx.togglePanel('acme.research', true)`.

`onActiveSymbol` tracks the active cell across multi-chart layouts whenever focus moves to another chart. `mount` can also return `onOpen` (invoked when the panel becomes visible, ideal for deferring expensive network requests) and `onChart` (invoked when the active chart reference changes).

`registerSidePanel` also supports floating panels (`overlay: true`), a Maximize toggle (`maximizable: true`), and custom headers (`header: 'none'`). See [Side panels](/vela/contributing/plugin-sdk#side-panels--registersidepanel) and [Layout regions](/vela/contributing/plugin-sdk#layout-regions) in the core documentation for the complete descriptor schema.

You can mount any built-in module widget inside a custom panel using the same adapter pattern: instantiate the widget inside `mount`, pass `ctx.host` as `host`, synchronize props from `ctx`, and clean up in `destroy`. Reuse the installed module's controller (`watchlistController()`, `tradingController()`) so your custom panel stays synchronized with built-in surfaces (see [Standalone widgets](/vela-pro/modules/widgets)).

## Bottom dock panels [#bottom-dock-panels]

The bottom dock is Vela Pro's collapsible panel region beneath the chart grid, hosting surfaces such as the trading panel and strategy tester. It displays one active panel at a time, supports top-edge drag resizing and full-column maximization, and persists its open panel ID and height in the workspace state document. Call `registerBottomPanel` to add a panel to the dock.

```ts
import { registerIcon } from '@luxalgo/vela/plugin';
import { registerBottomPanel } from '@luxalgo/vela-pro';
import { onActiveSymbol } from '@luxalgo/vela-pro/plugin';

registerIcon('acme-news', '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor"><path d="M2.5 3.5h9v9h-9zM11.5 6h2v6.5h-2M5 6.5h4M5 9.5h4"/></svg>');

registerBottomPanel({
    id: 'acme.news',
    title: 'News',
    icon: 'acme-news',
    description: 'Headlines for the symbol on the chart.',
    order: 30,
    minHeight: 120,
    collapseBelow: 160,
    mount: (ctx, body, header) => {
        const list = document.createElement('ul');
        body.append(list);
        let visible = false;
        let symbol = '';
        const load = async (): Promise<void> => {
            const asked = symbol;
            if (!visible || !asked) return;
            const res = await fetch(`/api/news?symbol=${encodeURIComponent(asked)}`);
            const headlines = (await res.json()) as string[];
            if (asked !== symbol) return; // discard stale response if symbol changed mid-flight
            list.replaceChildren(...headlines.map((text) => Object.assign(document.createElement('li'), { textContent: text })));
            header.setCount(headlines.length);
        };
        const offSymbol = onActiveSymbol(ctx, (next) => {
            symbol = next;
            void load();
        });
        return {
            onOpen: () => {
                visible = true;
                void load();
            },
            onClose: () => {
                visible = false;
            },
            destroy: offSymbol,
        };
    },
});
```

`mount` executes once per workspace when the bottom dock initializes rather than waiting for the first open, allowing panels to subscribe to background state while hidden. Defer network polling or heavy rendering to `onOpen` and pause it in `onClose`.

Bottom panels receive a toggle button on the side rail by default, and can be opened programmatically via `bottomDock(ctx)?.open('acme.news')`.

| Descriptor field           | Default        | Description                                                                                                                                                    |
| -------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                       | Required       | Stable identifier persisted in the workspace state document when open.                                                                                         |
| `title`, `icon`            | Required       | Panel title and side rail icon name.                                                                                                                           |
| `description`              | None           | Hover-card description shown on the side rail button.                                                                                                          |
| `order`                    | `100`          | Sort order among bottom panels and their rail buttons (Trading uses `10`).                                                                                     |
| `rail`                     | `true`         | Adds a toggle button on the side rail. Pass `false` for panels opened exclusively from code (like the strategy tester).                                        |
| `restoreOpen`              | Matches `rail` | Restores this panel on reload when saved state had it open.                                                                                                    |
| `minHeight`                | `140`          | Minimum dock height in pixels while this panel is active.                                                                                                      |
| `collapseBelow`            | None           | Drag threshold in pixels below which releasing the resize handle snaps the panel to its minimum height.                                                        |
| `chrome`                   | `'header'`     | `'header'` renders the standard dock title bar with maximize and close buttons; `'none'` omits the title bar so the panel renders custom chrome inside `body`. |
| `mount(ctx, body, header)` | Required       | Populates `body` and optionally returns `{ onOpen, onClose, destroy }`.                                                                                        |

The `header` argument passed to `mount` controls the dock frame for your panel:

| Member                              | Description                                                                                                         |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| `slot`                              | Right-aligned `HTMLElement` in the dock title bar for mounting compact panel controls while active.                 |
| `setCount(count)`                   | Displays a numeric badge next to the panel title, or hides it when `null`.                                          |
| `close()`                           | Closes the bottom dock.                                                                                             |
| `isMaximized()`, `setMaximized(on)` | Reads or toggles full-height maximization over the chart column.                                                    |
| `fold(height)`                      | Locks the dock to a fixed `height` in pixels with resizing disabled while active, or restores resizing when `null`. |

When using `chrome: 'none'`, wire your custom close and maximize controls to `header.close()` and `header.setMaximized(...)`, and use `header.fold(40)` if your panel supports collapsing into a compact single-row bar.

`bottomDock(ctx)` returns the workspace's dock controller, or `null` when the bottom dock is disabled:

| Member               | Description                                                                             |
| -------------------- | --------------------------------------------------------------------------------------- |
| `open(id?)`          | Opens the dock to `id`, or reopens the most recently viewed panel when `id` is omitted. |
| `close()`            | Closes the dock.                                                                        |
| `toggle(id)`         | Opens `id`, or closes the dock if `id` is already active.                               |
| `setMaximized(on)`   | Expands the dock over the chart column or restores normal split height.                 |
| `isOpen`, `active`   | Current open state and active panel ID.                                                 |
| `onChange(listener)` | Subscribes to open, close, and panel-switch events. Returns an unsubscribe function.    |

## Side rail items [#side-rail-items]

Side panels and bottom panels register their side rail buttons automatically. Use `registerRailItem` to add a standalone action button to the side rail that runs custom logic instead of toggling a panel.

```ts
import { registerIcon } from '@luxalgo/vela/plugin';
import { registerRailItem } from '@luxalgo/vela-pro';

declare function openDepositDialog(host: HTMLElement): void;

registerIcon('acme-deposit', '<svg viewBox="0 0 16 16" fill="none" stroke="currentColor"><path d="M8 2.5v8M5 7.5l3 3 3-3M3 13.5h10"/></svg>');

registerRailItem({
    id: 'acme.deposit',
    title: 'Deposit',
    icon: 'acme-deposit',
    description: 'Add funds to your account.',
    order: 50,
    run: (ctx) => openDepositDialog(ctx.host),
});
```

| Descriptor field          | Description                                                                                                           |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
| `id`                      | Unique action identifier used for ordering and filtering in `sideRail` layout options.                                |
| `title`, `icon`           | Accessible label and registered icon name.                                                                            |
| `description`, `shortcut` | Optional hover-card description and keyboard shortcut hint.                                                           |
| `order`                   | Ascending sort order among rail items (defaults to `100`).                                                            |
| `run(ctx)`                | Click handler invoked with the workspace's `WidgetContext`.                                                           |
| `active(ctx)`             | Optional predicate returning `true` when the button should render in its active/pressed state.                        |
| `subscribe(ctx, refresh)` | Optional subscription hook that calls `refresh()` whenever `active(ctx)` changes and returns an unsubscribe function. |

Custom rail items appear in the lower rail group by default. You can customize rail grouping and visibility via `enableVelaPro({ sideRail: { top, bottom, exclude } })`; users cannot reorder or hide rail entries from the UI. Call `sideRail(ctx)?.setBadge(id, count)` to display an unread or activity badge on any panel or rail item button.

Under the hood, the side rail builds on the core sidebar (`target: 'sidebar'`). See [The sidebar](/vela/contributing/plugin-sdk#the-sidebar) in the core documentation and [Interface layout](/vela-pro/customization/interface) for rail placement options.

## Related [#related]

* [Standalone widgets](/vela-pro/modules/widgets)
* [Custom modules](/vela-pro/modules/extending/custom-modules)
* [Workspace layout](/vela-pro/charts/interface)
* [Plugin state](/vela-pro/persistence/stores/plugin-state)
