#Configuration

Every setting in Tickline lives in one options object. You can pass it in four ways, and they all do the same thing:

// 1. The Chart class
const chart = new Chart(element, { timeframe: "5m", grid: { vertical: false } });

// 2. Later, on a Chart or a <trade-chart>: only what you pass changes
chart.setOptions({ crosshair: { mode: "free" } });

// 3. The options property of <trade-chart> (same as setOptions)
document.querySelector("trade-chart").options = { legend: { ohlc: false } };

<!-- 4. As JSON in the options attribute: useful for server-rendered pages (Razor, PHP, Django, Rails) -->
<trade-chart options='{"timeScale": {"rightPadding": 0.1}, "labels": {"live": "Live"}}'></trade-chart>

The most common settings also have their own attributes (see Attributes).

How settings merge. Groups merge with what is already set, so { grid: { vertical: false } } turns off the vertical grid and leaves everything else alone. Lists (such as drawings.colors) and functions (such as format.price) are replaced, not merged. Values outside their range are clamped, for example series.candleWidth stays between 0.1 and 1.

Reading settings. chart.options returns every setting with its current value, defaults included. It's a copy, so changing it does nothing; use setOptions instead.

Order on <trade-chart>. When the element starts: defaults, then the options attribute, then the other attributes, then anything you passed to setOptions before it was in the page. After that, the last change wins, whichever way it was made. Removing an attribute puts that setting back to its default.

#Contents

• General
• layout: sizes and spacing
• series: candles and lines
• grid
• priceScale
• timeScale: zoom range and right padding
• crosshair
• legend
• lastPrice: live price line, tag, pulse, countdown
• livePosition: keep the live price at a fixed place on screen
• watermark
• interaction: pan, zoom, keyboard, editing
• animation: speed, durations and easing
• history: loading older candles page by page
• drawings
• format: your own number and date formats
• labels: every piece of text, for translation
• ui: the built-in buttons of <trade-chart>
• theme: colours and fonts
• Indicator styles
• Attributes
• Recipes

#General

Shorthands kept for convenience: animate (= animation.enabled), animationSpeed (= animation.speed), countdown (= lastPrice.countdown), priceLine (= lastPrice.line), rightPadding (= timeScale.rightPadding), minVisibleCandles (= timeScale.minVisibleCandles), emphasisDigits (= lastPrice.emphasisDigits).

#layout

#series

Colours of candles and lines come from the theme (up, down, line, areaTop, areaBottom).

#grid

The colour is the theme's grid.

#priceScale

#timeScale

#crosshair

The colours are the theme's crosshair, pillBackground and pillText.

#legend

#lastPrice

#livePosition

Keeps the live price at a fixed place on screen while the chart follows it. Both values are a share of the chart, from 0 to 1, or null.

chart.setOptions({ livePosition: { x: 0.5, y: 0.5 } });  // live price in the centre of the chart
chart.setOptions({ livePosition: { x: 0.8, y: 0.5 } });  // 80% across, at mid height
chart.setOptions({ livePosition: { x: 0.5 } });          // centred across; the scale still fits the prices
chart.setOptions({ livePosition: { x: null, y: null } }); // back to normal

<trade-chart live-position="center"></trade-chart>       <!-- or "0.8 0.5", or "0.5" for x only -->

With y set, the price scale is chosen so the live price stays at that height and every price in view still fits. When the user scrolls back in time, the chart stops following and the scale fits the prices again; going back to live (⌖, End or double-click) puts the price back in place.

#watermark

Large, faint text behind the candles.

<trade-chart symbol="EUR/USD" watermark="{symbol}"></trade-chart>

#interaction

Turn all of them off for a chart that only displays prices:

chart.setOptions({ interaction: { pan: false, wheelZoom: false, pinchZoom: false, keyboard: false, doubleClickToLive: false } });

#animation

See Animation.

#history

See Loading history page by page.

#drawings

#format

Your own formatting functions. Each one is optional; without it, the built-in format (or locale) is used.

kind tells you which label is wanted: "seconds", "minutes" (axis times), "day", "days" (axis dates), "month", "crosshair" or "drawing". tzOffset is the chart's offset from UTC in minutes, already worked out for timezone: "local".

chart.setOptions({
  format: {
    price: (v, d) => "$" + v.toFixed(d),
    time: (t, kind, tz) => {
      const d = new Date(t + tz * 60_000); // shift, then read the UTC fields
      return kind === "seconds" || kind === "minutes"
        ? `${d.getUTCHours()}h${String(d.getUTCMinutes()).padStart(2, "0")}`
        : d.toISOString().slice(0, 10);
    },
    indicator: (v) => (Math.abs(v) >= 1000 ? (v / 1000).toFixed(1) + "k" : v.toFixed(1)),
  },
});

Functions can't go in the JSON options attribute; use locale there, or call setOptions from a script.

#labels

Every piece of text the chart shows, for translation. {n} in zoomLimit becomes the number of candles.

chart.setOptions({
  locale: "es-ES",
  labels: {
    open: "A", high: "Máx", low: "Mín", close: "C",
    zoomIn: "Acercar", zoomOut: "Alejar", backToLive: "Volver al directo", live: "En directo ▸",
    zoomLimit: "Zoom máximo ({n} velas). Elige un intervalo menor para ver más detalle.",
    delete: "Borrar", tools: { trend: "Línea de tendencia" },
  },
});

Indicator names come from their definitions; register your own indicator to name it differently.

#ui

The HTML controls of <trade-chart>. The Chart class has no built-in buttons and ignores these.

On touch screens the zoom, image and full-screen buttons stay visible (ui.controlsVisible). On small charts (narrower than 520 px or shorter than 420 px) the drawing tools fold into one pencil button.

Each control has a part name for styling from outside: chart, controls, live-button, range-buttons, drawing-tools, drawing-bar, text-editor and toast.

trade-chart::part(drawing-tools) { top: 12px; }
trade-chart::part(live-button) { border-radius: 999px; }

#theme

theme is "dark" (default), "light", or overrides on top of one of them:

chart.setOptions({ theme: { base: "light", up: "#16a34a", down: "#dc2626", font: "Inter, sans-serif" } });

On <trade-chart>, every theme colour is also a CSS variable, so you can theme charts from your stylesheet. The order is: the preset (theme attribute), then CSS variables, then colours set with setOptions.

Two more variables style the HTML message: --tl-toast-background and --tl-toast-text. chart.currentTheme (or element.currentTheme) returns the colours in use.

#Indicator styles

addIndicator(id, params, style) takes a third argument for that one indicator:

const rsi = chart.addIndicator("rsi", { period: 21 }, { colors: ["#f59e0b"], levels: [20, 50, 80], height: 0.18 });
chart.updateIndicator(rsi, undefined, { width: 2 }); // change the style later

chart.indicatorList reports each indicator's params and style, so you can save and restore a user's setup.

#Attributes

Attributes set the most common settings without any JavaScript.

#Recipes

Keep the live price in the centre of the screen:

chart.setOptions({ livePosition: { x: 0.5, y: 0.5 } });

A download button of your own, and full screen from your own button:

saveButton.onclick = () => chart.downloadImage("my-chart.png", { pixelRatio: 2 });
const blob = await chart.toBlob({ type: "image/jpeg", quality: 0.9 }); // to upload or share
fullButton.onclick = () => chart.toggleFullscreen();                   // <trade-chart> only

A small sparkline with no axes, legend or controls:

<trade-chart type="area" legend="false" grid="none" controls="none" crosshair="hidden" style="height: 80px"
  options='{"priceScale": {"visible": false}, "timeScale": {"visible": false, "rightPadding": 0.02},
            "lastPrice": {"line": "none", "countdown": false}, "interaction": {"pan": false, "wheelZoom": false, "pinchZoom": false}}'>
</trade-chart>

A chart that scrolls with the page instead of zooming on the mouse wheel:

chart.setOptions({ interaction: { wheelZoom: false } });

Your brand colours:

trade-chart {
  --tl-background: #0f1115;
  --tl-up: #00c805;
  --tl-down: #ff5000;
  --tl-accent: #7c3aed;
  --tl-font: "Inter", sans-serif;
}

Only some drawing tools, in your language:

<trade-chart drawing-tools="horizontal, trend" options='{"labels": {"tools": {"horizontal": "Niveau", "trend": "Tendance"}}}'></trade-chart>

Save and restore a user's chart:

const saved = { options: { type: chart.options.type }, indicators: chart.indicatorList, drawings: chart.drawings };
localStorage.setItem("my-chart", JSON.stringify(saved));

// later
const s = JSON.parse(localStorage.getItem("my-chart"));
chart.setOptions(s.options);
s.indicators.forEach((i) => chart.addIndicator(i.id, i.params, i.style));
chart.setDrawings(s.drawings);

Edit this page on GitHub