# Theming and branding (/vela-pro/customization/theme)



A single theme configures the chart canvas, the surrounding toolbars and menus from Vela's open-source core, and every Vela Pro panel. Pass a theme through the workspace `theme` option, customize panel styles with CSS custom properties and `data-part` selectors, and configure the corner attribution mark through `enableVelaPro()`.

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

enableVelaPro();

const acmeDark: VelaTheme = {
    background: '#0b0e14',
    textColor: '#c9d1d9',
    gridColor: '#1c2230',
    borderColor: '#30363d',
    upColor: '#3fb950',
    downColor: '#f85149',
    fontFamily: 'Inter, system-ui, sans-serif',
    ui: { accent: '#7c3aed', radius: 'sm' },
};

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

// Switch themes at runtime, for example from an application theme toggle:
workspace.setTheme('light');
```

## Applying a theme [#applying-a-theme]

The `theme` option accepts `'dark'` (the default), `'light'`, the ID of a registered theme, a `VelaTheme` object, or the return value of `createTheme()`. A `VelaTheme` object requires seven canvas fields (`background`, `textColor`, `gridColor`, `borderColor`, `upColor`, `downColor`, and `fontFamily`). Its optional `ui` property configures interface styling beyond the canvas, including `accent`, `radius`, `font`, individual `tokens`, and component overrides.

Calling `workspace.setTheme(theme)` accepts the same values at runtime. Every chart and UI panel updates immediately without rebuilding the workspace. Users can also switch between registered themes in the chart settings dialog under the **Canvas** tab (`Theme`).

Use `createTheme()` to derive a complete theme from a minimal color palette, and call `registerTheme()` to add it to the theme selector in chart settings:

```ts
import { createTheme, registerTheme } from '@luxalgo/vela';

const acmeLight = createTheme({
    colors: { background: '#fdfdfc', text: '#1f2328', accent: '#7c3aed' },
    radius: 'sm',
    font: 'Inter, system-ui, sans-serif',
    tokens: { 'surface-elev': '#f1f1ef' },
});

registerTheme({ id: 'acme-light', label: 'Acme Light', theme: acmeLight });
```

When you supply `colors`, `createTheme()` determines whether the scheme is light or dark from `background` and derives grid and border colors from `background` and `text`. See [Theming](/vela/ui/theming#the-tokens) in the core documentation for the full token catalog, and [What to change, and where](/vela/ui/what-to-change) for how each visual element maps to theme fields.

## Design tokens and scope [#design-tokens-and-scope]

| Surface                                                                                                               | Theme mechanism                                                                                                                                                     |
| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Chart canvas (background, candles, grid, axis labels)                                                                 | Drawn directly from the seven required `VelaTheme` fields rather than CSS                                                                                           |
| Core interface (topbar, drawing toolbar, menus, dialogs, status line)                                                 | Styled with `--vela-*` CSS custom properties derived from the active theme                                                                                          |
| Vela Pro panels and dialogs (watchlist, alerts, order book, trading, journal, calendar, strategy tester, bottom dock) | Styled with the same `--vela-*` tokens; profit and loss values read `--vela-profit` and `--vela-loss`, and buy and sell controls read `--vela-up` and `--vela-down` |
| Pine code editor                                                                                                      | Editor surface follows the workspace theme, while syntax token colors use a separate configuration option                                                           |
| Vela Pro chart types (footprint cells, TPO blocks)                                                                    | Controlled by dedicated chart-type color settings in the chart settings dialog                                                                                      |

Configure Pine code editor syntax colors through the `colors` option on `codeEditor`, which maps one color per token kind. See [Pine code editor](/vela-pro/indicators/pine/code-editor) for available keys.

Vela Pro inspects the active theme's background color and sets `data-vp-scheme="dark"` or `data-vp-scheme="light"` on the workspace root element so application CSS can target each color scheme. Both `sideRail` and `bottomDock` enable scheme tracking automatically. If you disable both features, call `enableSchemeTracking()` from `@luxalgo/vela-pro` directly.

In dark mode, Vela Pro panels override five foreground and border tokens with neutral gray and white values to preserve contrast in dense tables (`--vela-fg`, `--vela-fg-bright`, `--vela-fg-muted`, `--vela-border`, and `--vela-border-faint`). If your dark theme tints text or borders, that tint appears in the core toolbar and menus but not inside Vela Pro panels unless you set those five tokens explicitly:

```css
[data-vp-scheme='dark'] .vp-root,
[data-vp-scheme='dark'] .vela-panel[class*='vela-panel-vela-pro.'] {
    --vela-fg: #d7dce5;
    --vela-fg-bright: #f3f5f9;
    --vela-fg-muted: #8b93a3;
    --vela-border: rgb(215 220 229 / 12%);
    --vela-border-faint: rgb(215 220 229 / 6%);
}
```

## Styling panels with CSS [#styling-panels-with-css]

Vela Pro places its CSS inside the `vela.pro` cascade layer, which sits above the core layers (`vela.theme`, `vela.ui`, `vela.chrome`) and below `vela.custom` (where theme component overrides live). Unlayered CSS rules always take precedence over layered rules regardless of selector specificity, so standard rules in your application stylesheet override `vela.pro` without `!important`. Keep those rules outside any `@layer` block, because a cascade layer declared on your page before Vela's stylesheets load has lower priority than `vela.pro`.

Target panels using their root class and target internal elements using `data-part` attributes. Root classes and `data-part` values form the supported styling contract, whereas internal class names inside a panel are private implementation details that may change between releases.

| Root class   | Root `data-part`  | Panel                                     |
| ------------ | ----------------- | ----------------------------------------- |
| `.vp-wl`     | `watchlist-panel` | Watchlist                                 |
| `.vp-wlx`    | `watchlist-view`  | Watchlist (advanced view)                 |
| `.vp-alerts` | `alerts-panel`    | Alerts                                    |
| `.vp-ob`     | `orderbook-panel` | Order book                                |
| `.vp-ticket` | `order-panel`     | Order panel                               |
| `.vp-tp`     | `trading-panel`   | Trading panel                             |
| `.vp-jr`     | `journal-panel`   | Journal                                   |
| `.vp-jrm`    | `journal-view`    | Journal full view (also carries `.vp-jr`) |
| `.vp-cal`    | `calendar-panel`  | Calendar                                  |
| `.vp-st`     | `strategy-tester` | Strategy tester                           |
| `.vp-dock`   | `bottom-dock`     | Bottom dock                               |

Every panel root also carries `.vp-root`, where shared custom properties control spacing and sizing across all Vela Pro panels:

| Custom property                                                                       | Default                | Description                                                                             |
| ------------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------------------------------- |
| `--_radius`                                                                           | `6px`                  | Border radius of buttons and text inputs                                                |
| `--_row-h`                                                                            | `28px`                 | Row height of data tables                                                               |
| `--_island-bg`, `--_island-border`, `--_island-on`                                    | Derived from theme     | Track background, border, and active item fill for segmented controls and filter strips |
| `--vela-button-height-xs`, `--vela-button-height-sm`                                  | `24px`, `28px`         | Height of compact UI kit buttons inside panels                                          |
| `--vela-button-font-size-xs`, `--vela-button-font-size-sm`, `--vela-button-font-size` | `11px`, `12px`, `13px` | Font size of UI kit buttons inside panels                                               |

```css
/* Use sharper corners and taller table rows across all Vela Pro panels. */
.vp-root {
    --_radius: 2px;
    --_row-h: 32px;
}

/* Highlight best bid and ask prices on the order book ladder in the accent color. */
.vp-ob [data-part='rung'][data-best] [data-cell='px'] {
    color: var(--vela-accent);
    font-weight: 700;
}
```

To discover available `data-part` names inside a panel, inspect the rendered DOM in browser developer tools or check the component stylesheets under `plugins/<name>/src/`.

A small number of Vela Pro rules carry `!important` (such as hidden element visibility and structural layout rules in drawing menus). In CSS cascade layers, layered `!important` rules override unlayered normal declarations, so those properties cannot be overridden from unlayered rules.

Standalone widgets mounted outside a `VelaWorkspace` do not inherit theme variables from a workspace container. Apply theme tokens to the widget's container element with `ensureUIHost(element, theme)` from the UI kit, as shown in [Standalone widgets](/vela-pro/modules/widgets).

## Attribution and corner mark [#attribution-and-corner-mark]

By default, the core renders an attribution mark in the bottom-left corner of the chart. Calling `enableVelaPro()` sets `watermark` to `false` by default, leaving the corner empty unless you configure it explicitly.

```ts
import { enableVelaPro } from '@luxalgo/vela-pro';

enableVelaPro({ watermark: '<img src="/acme-mark.svg" alt="ACME" height="16">' });
```

| `watermark` value | Corner display                         |
| ----------------- | -------------------------------------- |
| `false` (default) | Hidden (no mark rendered)              |
| `true`            | Default attribution mark from the core |
| Non-empty string  | Custom text or HTML markup             |

The `watermark` setting applies to every chart and workspace created after `enableVelaPro()` runs. In a multi-chart workspace grid, a single mark renders in the bottom-left chart cell. Custom markup is placed inside a `.vela-attribution-custom` wrapper that handles positioning and sets an appropriate foreground text color (white on dark charts, black on light charts).

<Warning>
  The `watermark` string is inserted as raw HTML. Only pass static branding markup controlled by your application, and never pass user input or untrusted network data.
</Warning>

The `NOTICE` file shipped at `node_modules/@luxalgo/vela/NOTICE` governs attribution requirements for the core mark, which expects an equivalent visible attribution notice elsewhere when hidden or replaced unless covered by your commercial license. Refer to the [Developer License Agreement](https://www.luxalgo.com/licensing/) for the terms governing your deployment.

<Note>
  Both `enableVelaPro()` and `VelaWorkspace` accept an option named `watermark`. On `enableVelaPro()`, `watermark` configures the bottom-left corner attribution mark. On `VelaWorkspace`, `watermark` toggles the large faded symbol and timeframe background watermark behind the price pane.
</Note>

## Related [#related]

* [Interface layout](/vela-pro/customization/interface)
* [Theming](/vela/ui/theming) in the core documentation for tokens, component overrides, and cascade layers
* [Standalone widgets](/vela-pro/modules/widgets)
