@elitechart/themes

Prebuilt darkTheme and lightTheme for ChartForge plus the token contract for authoring custom themes. Themes are pure token maps over CSS custom properties (--cf-*), so you can swap themes wholesale or override individual tokens at runtime — no rebuild, no flicker.

Install

pnpm add @elitechart/themes @elitechart/core

@elitechart/core re-exports the ChartForgeTheme, ResolvedTheme, and CfTokenKey types, so this package is type-only at the type-import boundary.

Quick example

import { createChart } from '@elitechart/core';
import { darkTheme, lightTheme } from '@elitechart/themes';

const chart = createChart(container, {
  series: {
    /* … */
  },
  theme: darkTheme,
});

// Runtime swap — every layer repaints with the new tokens.
chart.setTheme(lightTheme);

// Partial override — change just the bullish candle color.
chart.patchTheme({ seriesUp: '#00d4aa' });

What's in the box

• darkTheme — the canonical ChartForge dark palette (high-contrast, green bull / red bear candles).
• lightTheme — high-contrast light palette tuned for embed contexts and printable reports.
• applyTheme(root, theme) / clearTheme(root) — apply a theme's tokens to any DOM element as CSS variables. The chart engine uses this internally; you can call it on your own UI shell to share tokens.
• registerTheme / getTheme / listThemes — a small in-memory registry for swapping themes by string id (useful when storing the active theme in localStorage).
• Re-exports the ChartForgeTheme, ResolvedTheme, CfTokenKey types so consumers don't need a direct @elitechart/core import for typing.

Token shape

import type { ChartForgeTheme } from '@elitechart/themes';

interface ChartForgeTheme {
  readonly name: string;
  readonly tokens: Readonly<Record<CfTokenKey, string>>;
}

CfTokenKey is the union of every supported CSS variable. The full token surface covers backgrounds (--cf-color-bg-canvas, --cf-color-bg-panel, --cf-color-bg-surface, --cf-color-bg-elevated), text (--cf-color-text-primary, --cf-color-text-secondary, --cf-color-text-muted), borders, grid, crosshair, series colors, accent + state colors, focus ring, typography (--cf-font-sans, --cf-font-mono), size + spacing scales, radii, motion durations, and z-index layers.

Build a custom theme from scratch

The fastest way to brand the chart is to clone darkTheme and override only the tokens that matter for your palette:

import { darkTheme } from '@elitechart/themes';
import type { ChartForgeTheme } from '@elitechart/themes';

export const oceanTheme: ChartForgeTheme = {
  name: 'ocean',
  tokens: {
    ...darkTheme.tokens,

    // Backgrounds — deeper blue-blacks
    '--cf-color-bg-canvas': '#0a1628',
    '--cf-color-bg-panel': '#0f1f3d',
    '--cf-color-bg-surface': '#152849',
    '--cf-color-bg-elevated': '#1d3358',

    // Brand accent
    '--cf-color-accent': '#22d3ee',
    '--cf-color-accent-hover': '#0891b2',
    '--cf-color-accent-active': '#0e7490',
    '--cf-color-accent-fill': 'rgba(34, 211, 238, 0.18)',

    // Series — keep the canonical green / red bull / bear pair
    '--cf-color-series-up': '#26a69a',
    '--cf-color-series-down': '#ef5350',

    // Grid + crosshair, slightly cooler
    '--cf-color-grid': 'rgba(125, 211, 252, 0.08)',
    '--cf-color-crosshair': 'rgba(125, 211, 252, 0.45)',
  },
};

chart.setTheme(oceanTheme);

The ...darkTheme.tokens spread gives you sensible defaults for every token you don't override (typography, spacing, motion, radii). Don't forget to also override the light counterpart if you want both modes to be branded.

Apply tokens to your own UI

The chart shares its design tokens with the surrounding app via applyTheme. Call it once on the root element your shell renders into:

import { applyTheme } from '@elitechart/themes';
import { darkTheme } from '@elitechart/themes';

applyTheme(document.documentElement, darkTheme);

Now your own CSS can reference the same variables (var(--cf-color-bg-surface), var(--cf-font-mono), etc.) and stay perfectly in sync with the chart at every theme swap. clearTheme(root) removes them.

Theme registry

If you ship multiple themes and want to look them up by id (e.g. from URL state or localStorage), use the registry helpers:

import { registerTheme, getTheme, listThemes, darkTheme, lightTheme } from '@elitechart/themes';

registerTheme(darkTheme);
registerTheme(lightTheme);
registerTheme(oceanTheme);

const active = getTheme(localStorage.getItem('theme-id') ?? 'chartforge-dark');
chart.setTheme(active ?? darkTheme);

console.log(listThemes()); // ['chartforge-dark', 'chartforge-light', 'ocean']

Compatibility

• Node 20.11+ for the SSR-safe import of theme objects (no DOM access at module scope).
• Browsers every modern browser supporting CSS custom properties — i.e. all evergreen Chrome / Safari / Firefox / Edge plus iOS Safari 16+ and Android Chrome.
• SSR safe. applyTheme is a no-op without a DOM element argument, so feature-detect or call only on mount.
• Tree-shakeable ESM + CJS dual emit, named exports only, sideEffects: false.

Links

• Source
• Changelog
• GitHub issues
• @elitechart/core · @elitechart/elitechart

License

MIT — see LICENSE.