# Candlestick Charts

## Content

A Candlestick chart displays price movement across trading intervals. Each candlestick represents a single category item and visualizes four values: **open**, **high**, **low**, and **close**.
This chart type is widely used in financial applications to analyze market direction, volatility, and short-term price behavior.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image.17c231.png?width=600)

## Value Configuration

A candlestick chart requires four numeric fields for each data point:

* `open`
* `high`
* `low`
* `close`

The recommended configuration is to bind these fields as a single value group using the `vectors` structure:

```javascript
values: [{
  vectors: {
    open:  { field: "open" },
    high:  { field: "high" },
    low:   { field: "low" },
    close: { field: "close" }
  }
}]
```

Bind the fields in the logical order open → high → low → close to ensure correct interpretation.
Legacy configurations that bind these fields as separate value items remain supported.

## Category Configuration

Candlestick charts support both flat and hierarchical category binding.
Example (hierarchical binding):

```javascript
category: {
  field: "month",
  child: {
    field: "day"
  }
}
```

If only a single category field is provided, the chart uses a flat category axis.

## Using Code

The following example creates a candlestick chart by binding OHLC fields and grouping the category axis by **Month > Day**.

```javascript
const sheet = spread.getActiveSheet();
sheet.name("Candlestick Chart");
const dataManager = spread.dataManager();

function createStockTable(dataManager) {
    return dataManager.addTable("Stock", {
        data: [
            // September - uptrend
            { month: "Sep", day: "01", open: 100, high: 105, low: 98,  close: 104 },
            { month: "Sep", day: "02", open: 104, high: 110, low: 103, close: 108 },
            { month: "Sep", day: "03", open: 108, high: 112, low: 106, close: 111 },
            { month: "Sep", day: "04", open: 111, high: 115, low: 109, close: 113 },
            { month: "Sep", day: "05", open: 113, high: 118, low: 112, close: 117 },
            { month: "Sep", day: "08", open: 117, high: 125, low: 116, close: 123 },
            { month: "Sep", day: "09", open: 123, high: 130, low: 121, close: 128 },
            { month: "Sep", day: "10", open: 128, high: 135, low: 126, close: 132 },

            // October - pullback then recovery
            { month: "Oct", day: "01", open: 132, high: 134, low: 125, close: 127 },
            { month: "Oct", day: "02", open: 127, high: 129, low: 120, close: 122 },
            { month: "Oct", day: "03", open: 122, high: 124, low: 118, close: 119 },
            { month: "Oct", day: "04", open: 119, high: 123, low: 117, close: 121 },
            { month: "Oct", day: "05", open: 121, high: 128, low: 120, close: 126 },
            { month: "Oct", day: "08", open: 126, high: 133, low: 125, close: 131 },
            { month: "Oct", day: "09", open: 131, high: 138, low: 130, close: 136 },
            { month: "Oct", day: "10", open: 136, high: 142, low: 134, close: 140 }
        ]
    });
}

const stockTable = createStockTable(dataManager);
await stockTable.fetch();

const dataChart = sheet.dataCharts.add("candlestickChart", 10, 10, 700, 400);

dataChart.setChartConfig({
    tableName: "Stock",
    plots: [{
        type: GC.Spread.Sheets.DataCharts.DataChartType.candlestick,
        encodings: {
            values: [{
                vectors: {
                    open: { field: "open" },
                    high: { field: "high" },
                    low: { field: "low" },
                    close: { field: "close" }
                }
            }],
            category: {
                field: "month",
                child: {
                    field: "day"
                }
            }
        },
        config: {
            palette: ["#2ECC71", "#E74C3C"]
        }
    }],
    config: {
        header: {
            title: "Daily Stock Prices"
        }
    }
});
```

![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260402.c44312.png?width=600)