Announcing Lightweight Charts 3.0

Jul 6, 2020

We’re excited to release Lightweight Charts 3.0. We’ve added the ability to have two price scales at the same time, determine the bar count from left/right of the visible data, use your own date format, override auto scale range, and much more. In this post, we’ll walk you through each of these updates and show you how to get started using our newest version of Lightweight Charts.

Breaking changes

First of all, this is a major release of the library, which has some breaking changes:

  • Both methods subscribeVisibleTimeRangeChange and unsubscribeVisibleTimeRangeChange have been moved from ChartApi to TimeScaleApi;
  • With our 3.0 release, you can specify the price axis you’d like to place the series on. The same goes for moving the series between price scales.

See our breaking changes doc with a comprehensive guide to help you migrate smoothly.

Two price scales

Since our first public version, the library has only been able to show one price scale at the same time (from left or from right), if at all. With version 3.0, you’ll be able to show up to two price scales at once. This means you can add two different series on the chart, put them on different price scales (one at the left one, the other at the right) and they’ll both be visible. In addition, you’ll have the ability to put several series on the same price scale, even if it’s an overlay. Thus creating your own study with several outputs where you can make every output as a separate series and put them all on the same price scale so they’ll be scaled together.

Counting bars and bar visibility

Let’s say you develop an app and you’ll need to implement continuous data loading for when a user scrolls to the left in the history (viewable here). This is a pretty basic feature for charting solutions.

The 3.0 version of the library has many improvements related to this feature. For instance, you can now get information about how many bars a series has from the left of the left visible bar or from the right of the right visible bar. You can also now make predictions and load new bars ahead so users won’t see any “freezing” or loading delays. For example, let’s say you start loading additional bars when a user scrolls to the left so the chart has the only 50-100 bars left in the history.

In addition, the API can also be applied to smoothly-syncing visible ranges (as seen on TradingView’s multichart, for example) between several charts. When one chart is moved, others are moved as well.

Date formats

Previously, we had a hard-coded list of available date formats (19 formats in total), so you weren’t able to customize and use your own format, which would be better fit to your requirements.

In 3.0 we’ve changed this, allowing you to use any custom string as a date format. For example, you can use `yyyy-dd` or even `yyyy`, which is suitable for seasonal charts.

A custom format can be any string, containing any number of date placeholders, which we’ll then replace with corresponding date values:

  • `yyyy` – full year (e.g. 2020)
  • `yy` – short year (e.g. 20)
  • `MMMM` – long month (e.g. July)
  • `MMM` – short month (e.g. Feb)
  • `MM` – numeric (with leading zero if needed) month (e.g. 03)
  • `dd` – day of month (with leading zero if needed) (e.g. 15)

Overriding series price range 

By default, the library uses all visible data on the chart to calculate price range while in auto scale mode. However, if you’d like to modify it in some way, for example, if you’re sure that the series shouldn’t have negative values, you can change the price range in a way that will allow it to project as non-negative, and the library will adopt the price range accordingly.

Ability to add a text to the series marker

Series markers are useful for improving a chart’s UX. They allow you to show markers (i.e. arrows, a circle, or square) next to a series’ bars. In our new version of the library, you can also specify a signature or text for each marker, allowing you to add captions and notes.

API to convert time to a coordinate and vice versa

Occasionally, it’s necessary to place a hint or text at the top of the library at a specific time on the chart. In our 3.0 version, we’ve added the ability to convert time to X coordinate and vice versa, essentially having the API set the screen coordinate. In addition, you can now get the width of the visible price scale (left or right). This can be useful, for example, if you have the left price scale displayed and you need to get an exact coordinate inside the chart.

Ability to hide price scale tick marks

Tick marks on the price scale might seem somewhat confusing to some, oftentimes because they look like a minus sign. However, now you can disable this symbol, causing the library to cease their display. This means no more confusing symbols filling your chart if you’d rather have that space cleared. 

More features, smaller bundle

One of the meanings of “lightweight” refers to size. The first version of the library was ~43.7KB in min.gz. Since then, we’ve added many new features and you may think that the size mimics the growth of these additions, but that’s where you’d be wrong.

In this release, we’ve applied various techniques to reduce the size of the library, allowing us to provide you with a smaller bundle size. Therefore, the 3.0 version of the library is 42.4KB in min.gz, even smaller than before, but stocked full of added features and tools.

Note that the techniques we’ve used here are not specific to lightweight charts. Meaning you can use them in your projects as well. If you are interested in learning more about our process, check the following GH #436 and GH #432, which highlight size reduction in the library. Our testing has shown that these techniques can reduce the size of a bundle by up to 30% in minified uncompressed form, and by up to 10% in min.gz.

A special thanks to our community

TradingView is a community of investors, traders, and programmers. We want to say thank you to all of our contributors who have helped with this release:

We have more to show you

We’ve only scratched the surface with this post regarding what’s new in Lightweight Charts 3.0. To see a full list of changes, we encourage you to check out our Github notes for more details and information. If you’d like to learn more about how Lightweight Charts can help you, please visit this page.

We hope you’ve enjoyed this update. As always, please continue sending us your comments, suggestions, and feedback. It is our pleasure to build for you.

Look first Then leap

TradingView is built for you, so make sure you're getting the most of our awesome features
Launch Chart