SDChart.js Documentation

SD Chart – User Documentation

Introduction

SD Chart provides interactive charts, supporting multiple visualization types including line, bar, histogram, pie, candlestick, scatter and geographic maps. It’s highly customizable and easy to integrate into your websites and applications.

Go To the interactive DEMO

Installation

  1. Include JavaScript

Include the following script:

<script src="path/to/sdChart.js"></script>

OR use this:

<script src="https://synchrodynamic.com/js/sdChart.js"></script>
  1. License Initialization

Initialize SD Chart with your provided license token:

sdChart.getInstance('YOUR_LICENSE_TOKEN')

Note: Validation only needs to be done once per page load. After your first chart, you can simply add your next chart with:

sdChart.getInstance()

License Validation

Your subscription grants you usage rights under the Synchrodynamic Automation Subscription Software License Agreement:

  • Non-exclusive, non-transferable license.
  • Regular subscription fees required.
  • Software use restricted to authorized subscribers.
  • No distribution, modification, reverse-engineering, sublicensing, or reselling permitted.

SD Chart automatically validates your license on load.

Get a License Here:

Basic Usage

Here’s a simple example to create a chart:

<div id="chartContainer"></div>
<script src="https://synchrodynamic.com/js/sdChart.js"></script>
<script>
    sdChart.getInstance("your-license-token").chart({
        elementContainer: 'chartContainer',
        chartType: 'line',
        labels: {x: "Time", y: "Price", size: 12},
        chartTitle: 'Monthly Sales',
        series: [{
                name: "sma",
                data: [["Jan", 120], ["Feb", 130], ["Mar", 140]],
                color: '#ffce00'
            }]
    });
</script>

Important Note before getting started

Your API KEY should be kept secure at all times. If you paste your key directly into JavaScript on a public webpage, it can be seen and then used by people that should not be using your key. Make sure to at minimum try something like this:

PHP Implementation:

Create a config file:

<?php
   echo $_SERVER['REMOTE_ADDR'];
   if ($_SERVER['REMOTE_ADDR'] !== '::1') {
       http_response_code(403);    
       die('Access denied.');
   }
   header('Content-Type: text/plain');
   header("Access-Control-Allow-Origin: *"); // Allow cross-origin requests if needed
   $api_key = "your-license-token";echo trim($api_key); // ✅ Ensure no extra spaces or newlines
   exit;
?>

Add a function to your javascript to call your API KEY:

function getApiKeySync() {
    let request = new XMLHttpRequest();
    request.open("GET", "config.php", false);
    request.send();

    if (request.status === 200) {
             return request.responseText.trim();
    } else {
             console.error("❌ Failed to fetch API key.");
             return null;
    }
  }

Then simply call it into a variable:

let api = "";
api = getApiKeySync();

For best results add your code for your charts inside of a function to call after the key is set.

Chart Types & Usage

Below is detailed usage guidance based on the chart type implementations:

Line Chart (Multi-Series Capable)

The Line Chart configuration can include any of the following properties. Each property corresponds to the tooltips you provided, describing its purpose or effect on the chart.

Available Properties

PropertyDescription
chartTitle“Used to set the main title of the chart.”
titleColor“Set the color of your Chart Title.”
labelX“Defines what the X-Axis Represents
(i.e Time).”
labelY“Defines what the Y-Axis Represents
(i.e Price).”
labelSize“Sets the size in pixels of all axes labels.”
labelColor“Set the color hover Labels.”
labelBackgroundColor“Set the background color of hover labels.”
labelOpacity“Set alpha channel for labels background color.”
seriesName“Give each series a series name
(Only one series name in interactive
chart creation).”
seriesData“The data that will be used to draw your chart.”
Expected to be an array of arrays or a similar
structure:
e.g. [[\"Jan\", 120], [\"Feb\", 130], ...]
seriesColor“The color your chart will be.”
crosshairColor“The vertical line of your crosshair while hovering.”
labelTicksX“Number of labels to span across the x-axis.”
labelTicksY“Number of labels to span across the y-axis.”
height“The max height of your chart.”
downsampleQuantity“Decrease the number of datapoints
in your chart.
Points are averaged together.
Zooming will unlock the exact points.”
disableInteraction“Remove all interaction modules
from your chart.”
axesTextColor“Sets the color of axes.”

Example Usage

Below is a minimal example showing how these properties might be combined into a configuration object for a Line Chart. The code snippet is for illustration and does not reference the interactive demo; it simply demonstrates how you might apply these properties in practice.

sdChart.getInstance(api).chart({
    elementContainer: 'lineChart',
    rangeSelector: {selected: 0,
        buttons: [
            {type: 'all', text: 'ALL'}
        ]
    },
    labels: {x: "Time", y: "Price", size: 12},
    chartTitle: "Line Chart",
    titleColor: "#000",
    chartType: "line",
    crosshair: {
        dot: "pink",
        cross: "cyan"
    },
    axesTextColor: "#000",
    series: [{
            name: "sma",
            data: lineChartData.sma,
            color: '#ffce00'
        }, {
            name: "close",
            data: lineChartData.closeLine,
            color: '#002fff'
        }, {
            name: "bollU",
            data: lineChartData.bollU,
            color: '#93ff00'
        }, {
            name: "bollL",
            data: lineChartData.bollL,
            color: '#ff00ef'
        }],
    downsampleQuantity: 80
});

Explanation of Key Properties in the Example

  • chartType: Declares this chart as a "line" chart.
  • chartTitle and titleColor: Set a main title and define its color.
  • labelX and labelY: Indicate what the horizontal (X) and vertical (Y) axes represent.
  • labelSize, labelColor, labelBackgroundColor, labelOpacity: Various styling options for the labels on the chart or hover elements.
  • seriesName: Name for the data series displayed (in a simplified scenario, only one series).
  • seriesData: The data points that define the line. In string form here, but often parsed or passed directly as an array.
  • seriesColor: The color used to draw the line.
  • crosshairColor: The color of the crosshair’s vertical line when hovering.
  • labelTicksX and labelTicksY: Dictate how many axis labels/ticks to show on each axis.
  • height: Maximum chart height in CSS units.
  • downsampleQuantity: Reduces the resolution of the dataset, which can be useful for performance on large datasets.
  • disableInteraction: If set to "true", can remove interactive elements like tooltips or crosshairs.

Bar Chart (Multi-Series Capable)

Bar charts are ideal for comparing data points across categories or illustrating variations across distinct groups.

Data Format

Each dataset in a bar chart consists of:

  • X-axis Label: Represents categories (e.g., time periods, products, or other groups).
  • Y-axis Value: Numerical value for each category, shown by bar height.

Configuration Breakdown

  • elementContainer:
    • The ID of the HTML container element for rendering the chart.
    • Example: 'barChart'
  • chartType:
    • Defines the chart style; must be 'bar' for bar charts.
  • chartTitle:
    • Title displayed at the top of the chart.
  • labels:
    • Customize axis labels and their size in pixels.
    • Example: {x: "Products", y: "Units Sold", size: 12}
  • axesTextColor:
    • Color for the axis labels.
  • titleColor:
    • Color of the chart title text (optional) Default: #000000 or Black.
  • crosshair: (optional)
    • Defines the appearance of the crosshair used for interactive chart exploration. Default: Red
  • series:
    • Array containing multiple datasets. Each dataset includes:
      • name: Identifier for the data series.
      • data: Array of data points ["label", value].
      • color: Bar color for the data series.
  • disableInteraction:
    • If set to true, disables interactive features. hover, zoom, navigation, and time buttons or disabled.

Example

<div id="chartContainer"></div>
<script src="https://synchrodynamic.com/js/sdChart.js"></script>
<script>
    sdChart.getInstance(api).chart({
        elementContainer: 'chartContainer',
        labels: {x: "Time", y: "Price", size: 12},
        chartTitle: "Bar Chart",
        titleColor: "#000",
        chartType: "bar",
        crosshair: {
            dot: "pink",
            cross: "blue"
        },
        axesTextColor: "#000",
        series: [
            {
                name: "Phone Sales",
                data: [["Jan", 100], ["Feb", 120]],
                color: '#718900'
            },
            {
                name: "Tablet Sales",
                data: [["Jan", 80], ["Feb", 90]],
                color: '#890000'
            },
            {
                name: "Subscription Sales",
                data: [["Jan", 60], ["Feb", 70]],
                color: '#008928'
            },
            {
                name: "Maintenance Plan Sales",
                data: [["Jan", 50], ["Feb", 65]],
                color: '#890089'
            }
        ],
        disableInteraction: true
    });
</script>

Use bar charts effectively for clear comparisons between multiple categories or time intervals.

Candle Chart (Single Series Only)

Candle charts effectively display open, high, low, and close values typically used for financial market data. Note: Dataset for this chart must be at least 20 or more.

Data Format

Each dataset for a candlestick chart requires data points formatted as:

  • [timestamp, open, high, low, close, volume]

Configuration Breakdown

  • elementContainer:
    • HTML container ID for chart rendering.
    • Example: 'chartContainer'
  • chartType:
    • Specify 'candle' to render a candlestick chart.
  • chartTitle:
    • Chart title shown at the top.
  • labels:
    • Customize axis labels and their size in pixels.
    • Example: {x: "Date", y: "Price ($)", size: 12}
  • axesTextColor:
    • Defines the color of the axis labels.
  • crosshair:
    • Appearance settings for the crosshair.
    • Default example: {dot: "pink", cross: "#00ff02"}
  • series:
    • Dataset configuration containing:
      • name: Name of the dataset.
      • data: Array of candlestick data points.
      • Example: data: [[timestamp, open, high, low, close, volume]]
      • color: Color for dataset representation.
  • candleColor:
    • Detailed color settings for candlesticks:
      • bodyPos: Color for positive movements.
      • bodyNeg: Color for negative movements.
      • wick: Wick color.
      • volumePos: Positive volume color.
      • volumeNeg: Negative volume color.
      • Additional properties for opacity and tooltip styling.
  • downsampleQuantity:
    • Limits the maximum number of data points displayed for performance enhancement.

Example

Use candlestick charts to visualize financial data with clarity and precision.

<div id="chartContainer"></div>
<script src="js/sdChart.js"></script>
<script>
    var candleData = [
        [1423785600000, 222.56, 242.5, 221.46, 236.13, 34767.14021622],
        [1423872000000, 235.8, 261.3, 235.51, 257, 40996.078904585], 
        [1423958400000, 257.01, 268.54, 228.2, 235.88, 52489.659208765],  
        [1424044800000, 235.34, 243.65, 228.62, 233.5, 24038.216024825], 
        [1424131200000, 233.5, 246.28, 231.5, 244, 20813.002], 
        [1424217600000, 243.82, 244.99, 231.01, 236.26, 20023.7506], 
        [1424304000000, 236.8133, 245.1133, 234.6466, 239, 8125.1393], 
        [1424390400000, 240.2, 248.98, 238.95, 244.5, 15949.20093802], 
        [1424476800000, 244.51, 247.73, 243.28, 245.54, 8237.596740665], 
        [1424563200000, 245.53, 247.78, 232.1, 236.5, 17086.76138654], 
        [1424649600000, 236.5, 241, 232.61, 239.4, 12138.193547205], 
        [1424736000000, 239.33, 240.99, 236.7, 239.73, 8455.629671295], 
        [1424822400000, 239.95, 240.83, 235.53, 237.99, 6885.098606735], 
        [1424908800000, 237.6533, 254.12, 234.08, 249.52, 6449.9186], 
        [1424995200000, 236.93, 262.8, 236.64, 255.05, 35548.611573185], 
        [1425081600000, 255.06, 257.4, 251.25, 255.7, 8796.754735475], 
        [1425168000000, 255.7, 266.91, 245.65, 262.4, 24221.875782595], 
        [1425254400000, 262.47, 279.61, 258.98, 277.41, 34181.37921494], 
        [1425340800000, 277.3, 294, 267.04, 283.75, 41335.33995843], 
        [1425427200000, 283.8, 285.99, 267, 273.33, 36396.654371465]
    ];
    sdChart.getInstance("your-license-token").chart({
        elementContainer: 'chartContainer',
        labels: {x: "Time", y: "Price", size: 12},
        chartTitle: "Candle Chart",
        titleColor: "#000",
        chartType: "candle",
        crosshair: {
            dot: "pink",
            cross: "#00ff02"
        },
        axesTextColor: "#000",
        series: [{
                name: "BTC",
                data: candleData,
                color: '#718900'
        }],
        candleColor: {
            bodyPos: "#00ff7e",
            bodyNeg: "#ff9765",
            bodyOutline: "#000000",
            wick: "#ff00ec",
            O: "#00fff9",
            H: "#0037ff",
            L: "#ff1300",
            C: "#ffac00",
            volumePos: "#0b5a00",
            volumeNeg: "#5a1e00",
            volumeOpacity: 0.3,
            infoBackground: "#ffffff",
            infoColor: "#000000", 
            infoOpacity: "0.8"
        },
        downsampleQuantity: 100
    });
</script>

Histogram Chart (Single Series Only)

Histograms effectively display the distribution and frequency of numerical data within defined intervals or buckets.

Data Format

Histogram data is a simple array of numeric values:

  • Each number represents a single observation.
  • The data will automatically be sorted into intervals (buckets).

Configuration Breakdown

  • elementContainer:
    • ID of the HTML container for chart rendering.
    • Example: 'chartContainer'
  • chartType:
    • Defines the type of chart; must be 'histogram' for histograms.
  • chartTitle:
    • Title displayed at the top of the chart.
  • labels: (optional)
    • Customize axis labels and their font size.
    • Example: {x: "Values", y: "Frequency", size: 12}
  • titleColor:
    • Color of the chart title text (default is black).
  • crosshair: (optional)
    • Customize the crosshair appearance.
  • series:
    • An array containing dataset configurations:
      • name: Identifier for dataset.
      • data: Array of numerical observations.
      • color: Color for bars in the histogram.
  • buckets:
    • Number of intervals the data is divided into.
  • height:
    • Sets the chart container height (e.g., '400px').
  • downsampleQuantity:
    • Limits displayed data points for performance optimization.

Example

Use histogram charts to clearly visualize and analyze data distributions and frequencies.

<div id="chartContainer"></div>
<script src="js/sdChart.js"></script>
<script>
    const histogramData = [9, 9, 8, 15, 8, 10, 7, 10, 8, 11, 16];
    sdChart.getInstance().chart({
        elementContainer: 'chartContainer',
        labels: {x: "", y: "FREQUENCY", size: 10},
        chartTitle: "Histogram Chart",
        titleColor: "#000",
        chartType: "histogram",
        crosshair: {
            dot: "pink",
            cross: "#00ff02"
        },
        axesTextColor: "#000",
        series: [{
                name: "",
                data: histogramData,
                color: '#718900'
            }],
        buckets: 9,
        height: "400px",
        downsampleQuantity: 1000
    });
</script>

Pie Chart (Single Series Only)

Pie charts effectively display proportions and percentages clearly in a circular visual format.

Data Format

Pie chart data should be structured as:

  • Array of pairs ["Category", value] where the value represents the proportion of each category.

Configuration Breakdown

  • elementContainer:
    • ID of the HTML element where the chart will be rendered.
    • Example: 'chartContainer'
  • chartType:
    • Must be 'pie' for pie charts.
  • chartTitle:
    • The title displayed at the top of the chart.
  • labels:
    • Customize axis labels (used mainly for consistency).
  • titleColor:
    • Color of the chart title text (default is black).
  • series:
    • Array containing dataset configurations:
      • name: Identifier for the dataset.
      • data: Array of category-value pairs.
  • pieStyle:
    • Customize the visual appearance of pie slices:
      • border: Border color around slices.
      • random: Randomizes slice colors if set to true.
      • font: Customizes the size and style of slice labels.
      • colors: Custom array of colors for each slice.

Example

Use pie charts to clearly present and compare proportional data visually.

<div id="chartContainer"></div>
<script src="js/sdChart.js"></script>
<script>
    const pieChartData = [
                ["a", .44],
                ["b", .15], 
                ["c", .07], 
                ["d", .34]
    ];
    sdChart.getInstance().chart({
        elementContainer: 'chartContainer',
        labels: {x: "Time", y: "Price", size: 10},
        chartTitle: "Pie Chart",
        titleColor: "#000",
        chartType: "pie",
        crosshair: {
            dot: "pink",
            cross: "#00ff02"
        },
        axesTextColor: "#000",
        series: [{
                name: "",
                data: pieChartData,
                color: '#718900'
        }],
        pieStyle: {
            border: "#FFFF00",
            random: false,
            font: {size: "30", style: "Arial"},
            colors: ["#00e0df", "#b9e000", "#00e002", "#9200e0"] //Remove these if random set to true.
        },
        height: "800px"
    });
</script>

Scatter Chart (Multi-Series Capable)

Scatter charts effectively display correlations, clusters, and distribution of data points across two variables.

Data Format

Scatter chart data consists of pairs representing:

  • X-axis value: Represents the independent variable.
  • Y-axis value: Represents the dependent variable.

Configuration Breakdown

  • elementContainer:
    • ID of the HTML container for rendering the chart.
    • Example: 'chartContainer'
  • chartType:
    • Must be 'scatter' to render a scatter chart.
  • chartTitle:
    • Title displayed above the chart.
  • labels:
    • Customize axis labels and their sizes in pixels.
    • Example: {x: "Time", y: "Price", size: 10}
  • axesTextColor:
    • Defines the color of the axis labels.
  • titleColor:
    • Color of the chart title text (default black).
  • crosshair: (optional)
    • Customize appearance of the crosshair for data exploration.
  • series:
    • Array of datasets, each dataset includes:
      • name: Name of dataset.
      • data: Array of [xValue, yValue] pairs.
      • color: Color representing dataset points.

Example

Use scatter charts to identify relationships, patterns, or anomalies in your data visually.

<div id="chartContainer"></div>
<script src="js/sdChart.js"></script>
<script>
    const testScatterData = [
        [3, 120], [7, 300], [12, 450], [18, 230], [22, 310],
        [25, 80], [29, 210], [34, 400], [38, 150], [42, 360],
        [45, 275], [48, 490], [52, 200], [55, 310], [60, 450],
        [63, 180], [68, 260], [70, 350], [75, 90], [78, 420],
        [80, 140], [85, 500], [88, 290], [90, 370], [93, 250],
        [95, 410], [98, 280], [5, 130], [10, 310], [15, 440],
        [20, 220], [28, 190], [33, 390], [37, 170], [41, 350],
        [44, 255], [47, 470], [51, 190], [54, 300], [58, 440],
        [61, 160], [66, 240], [72, 330], [77, 100], [81, 390],
        [83, 130], [87, 480], [89, 270], [92, 360], [96, 240]
    ];
    const testScatterData1 = [
        [2, 69], [12, 347], [11, 67], [13, 69], [35, 303],
        [49, 7], [4, 356], [55, 18], [83, 403], [76, 309],
        [47, 128], [41, 78], [99, 163], [38, 444], [20, 180],
        [59, 73], [1, 325], [76, 23], [53, 134], [93, 367],
        [79, 100], [88, 206], [71, 54], [8, 352], [88, 322],
        [36, 15], [56, 257], [8, 436], [73, 30], [91, 7],
        [11, 305], [9, 334], [81, 500], [33, 35], [91, 371],
        [70, 409], [69, 473], [58, 35], [21, 157], [63, 204],
        [80, 19], [93, 407], [21, 383], [20, 59], [58, 472],
        [62, 15], [92, 30], [23, 356], [61, 140], [87, 366]
    ];
    sdChart.getInstance().chart({
        elementContainer: 'chartContainer',
        labels: {x: "Time", y: "Price", size: 9},
        chartTitle: "Scatter Chart",
        titleColor: "#000",
        chartType: "scatter",
        crosshair: {
            dot: "pink",
            cross: "#00ff02"
        },
        axesTextColor: "#000",
        series: [{
                name: "Scatter 1",
                data: testScatterData,
                color: '#718900'
        },
        {
                name: "Scatter 2",
                data: testScatterData1,
                color: '#0b5a00'
        }],
        height: "400px",
        downsampleQuantity: 1000
    });
</script>

Map Chart (Single Series Only)

Map charts visually represent geographical data, effectively highlighting variations and patterns across different regions.

Data Format

Map data should be structured as an array of objects, each containing:

  • ucName:
    • The uppercase name of the geographical region (e.g., state names).
  • value:
    • Numeric value representing the data intensity or frequency for each region.

Configuration Breakdown

  • elementContainer:
    • ID of the HTML container element for chart rendering.
    • Example: 'chartContainer'
  • chartType:
    • Use 'map' to render geographical maps.
  • chartTitle:
    • Title displayed at the top of the chart.
  • titleColor:
    • Color of the chart title text (default black).
  • mapVariables:
    • Object containing detailed configuration for map appearance and behavior:
      • stateData: Array of data points structured as explained above.
      • darkmode: Boolean, toggles dark mode for the map.
      • colors: Object defining color gradient:
        • low: Color for low-value regions.
        • mid: Color for medium-value regions.
        • high: Color for high-value regions.
      • highlightColor: Color for highlighting regions on hover or selection.

Example

Use map charts to visualize and analyze geographic data clearly and intuitively.

<div id="chartContainer"></div>
<script src="js/sdChart.js"></script>
<script>
    const presidentsByState = [
        {"ucName": "ALABAMA", "value": 1},
        {"ucName": "ALASKA", "value": 0},
        {"ucName": "ARIZONA", "value": 1},
        {"ucName": "ARKANSAS", "value": 1},
        {"ucName": "CALIFORNIA", "value": 1},
        {"ucName": "COLORADO", "value": 0},
        {"ucName": "CONNECTICUT", "value": 1},
        {"ucName": "DELAWARE", "value": 0},
        {"ucName": "FLORIDA", "value": 0},
        {"ucName": "GEORGIA", "value": 1},
        {"ucName": "HAWAII", "value": 1},
        {"ucName": "IDAHO", "value": 0},
        {"ucName": "ILLINOIS", "value": 2},
        {"ucName": "INDIANA", "value": 1},
        {"ucName": "IOWA", "value": 1},
        {"ucName": "KANSAS", "value": 1},
        {"ucName": "KENTUCKY", "value": 2},
        {"ucName": "LOUISIANA", "value": 0},
        {"ucName": "MAINE", "value": 0},
        {"ucName": "MARYLAND", "value": 0},
        {"ucName": "MASSACHUSETTS", "value": 4},
        {"ucName": "MICHIGAN", "value": 1},
        {"ucName": "MINNESOTA", "value": 1},
        {"ucName": "MISSISSIPPI", "value": 0},
        {"ucName": "MISSOURI", "value": 1},
        {"ucName": "MONTANA", "value": 0},
        {"ucName": "NEBRASKA", "value": 1},
        {"ucName": "NEVADA", "value": 0},
        {"ucName": "NEW HAMPSHIRE", "value": 1},
        {"ucName": "NEW JERSEY", "value": 1},
        {"ucName": "NEW MEXICO", "value": 0},
        {"ucName": "NEW YORK", "value": 5},
        {"ucName": "NORTH CAROLINA", "value": 2},
        {"ucName": "NORTH DAKOTA", "value": 0},
        {"ucName": "OHIO", "value": 7},
        {"ucName": "OKLAHOMA", "value": 0},
        {"ucName": "OREGON", "value": 0},
        {"ucName": "PENNSYLVANIA", "value": 3},
        {"ucName": "RHODE ISLAND", "value": 0},
        {"ucName": "SOUTH CAROLINA", "value": 1},
        {"ucName": "SOUTH DAKOTA", "value": 1},
        {"ucName": "TENNESSEE", "value": 3},
        {"ucName": "TEXAS", "value": 2},
        {"ucName": "UTAH", "value": 0},
        {"ucName": "VERMONT", "value": 2},
        {"ucName": "VIRGINIA", "value": 8},
        {"ucName": "WASHINGTON", "value": 0},
        {"ucName": "WEST VIRGINIA", "value": 0},
        {"ucName": "WISCONSIN", "value": 1},
        {"ucName": "WYOMING", "value": 0}
    ];
    sdChart.getInstance().chart({
        elementContainer: 'chartContainer',
        chartType: "map",
        chartTitle: "Map Chart",
        titleColor: "#000",
        mapVariables: {
            stateData: presidentsByState,
            darkmode: false,
            colors: {low: "#ff0000", mid: "#ffff00", high: "#00ff00"},
            highlightColor: "#ffffff"
        }
    });
</script>

License Validation

SD Chart requires an active subscription and license validation via the Synchrodynamic Automation API. If the license is invalid, the chart will not render.


Support & Feedback

For further assistance, please visit Synchrodynamic Automation.

Thank you for choosing SD Chart by Synchrodynamic Automation!

Conversation