# Candlestick Chart

> Candlestick chart is essentially multiple box plots placed next to one another into a sequence. It is often employed in to visualize price movement of financial instruments, such as forex, stock, bonds...

A candlestick chart is essentially a sequence of box-plot-like bars placed side by side. It is commonly used to visualize the price movement of financial instruments such as forex, stocks, and bonds.

- **Good for:** open-high-low-close price movement over time, stock and forex trading sessions, daily or weekly trading ranges.
- **Not great for:** a single value per period (use a line or bar chart), non-time-series data, or categories without high and low bounds.

<!--  -->

## Syntax

Use the following AML definition to add the Candlestick Chart to your custom chart library.

```aml
CustomChartDef candlestick_chart {
  label: 'Candlestick Chart'
  description: 'To visualize the open, high, low, and close price movement of financial instruments over time.'
  fields {
    field date {
      label: 'Date'
      type: 'dimension'
      data_type: 'date'
      sort {
        apply_order: 1
        direction: 'asc'
      }
    }
    field low {
      label: 'Low'
      type: 'measure'
      data_type: 'number'
      sort {
        apply_order: 2
        direction: 'asc'
      }
    }
    field high {
      label: 'High'
      type: 'measure'
      data_type: 'number'
      sort {
        apply_order: 3
        direction: 'asc'
      }
    }
    field open {
      label: 'Open'
      type: 'measure'
      data_type: 'number'
      sort {
        apply_order: 4
        direction: 'asc'
      }
    }
    field close {
      label: 'Close'
      type: 'measure'
      data_type: 'number'
      sort {
        apply_order: 5
        direction: 'asc'
      }
    }
  }

  	options {
		option tooltip {
			type: 'toggle'
			label: 'Show tooltip'
			default_value: true
		}
		option green_candle {
			type: 'color-picker'
			label: 'Green candlestick'
			default_value: 'green'
		}
    option red_candle {
			type: 'color-picker'
			label: 'Red candlestick'
			default_value: 'red'
		}
	}

  template: @vgl
  {
    "data": {
      "values": @{values}
    },
    "layer": [
      {
        "mark": "rule",
        "params": [
          {"name": "normalPointSelection", "select": {"type": "point", "toggle": "true", "clear": "mouseup"}},
          {"name": "hoverPointSelection", "select": {"type": "point", "on": "mouseover", "clear": "mouseout"}}
        ],
        "encoding": {
          "y": {"field": @{fields.low.name}},
          "y2": {"field": @{fields.high.name}}
        }
      },
      {
        "mark": {
          "type": "bar",
          "tooltip": @{options.tooltip.value}
        },
        "encoding": {
          "y": {"field": @{fields.open.name}},
          "y2": {"field": @{fields.close.name}}
        }
      }
    ],
    "encoding": {
      "x": {
        "type": "temporal",
        "field": @{fields.date.name}
      },
      "y": {
        "axis": {
          "title": "Price"
        },
        "type": "quantitative",
        "scale": {
          "zero": false
        }
      },
      "color": {
        "condition": {
          "test": "datum['@{fields.open.name}'] < datum['@{fields.close.name}']",
          "value": @{options.green_candle.value}
        },
        "value": @{options.red_candle.value}
      }
    },
    "holisticsConfig": {
      "crossFilterSignals": ["normalPointSelection"],
      "contextMenuSignals": ["hoverPointSelection"]
    },
    "config": {
      "background": null,
      "view": {"stroke": null},
      "font": "Inter",
      "axis": {
        "title": null,
        "ticks": false,
        "labelPadding": 10,
        "labelFontSize": 11,
        "labelColor": "#858B9E",
        "titleColor": "#858B9E",
        "labelOverlap": "parity",
        "gridDash": [8, 3],
        "gridColor": "#F4F6F8",
        "domainColor": "#bec1cb"
      },
      "axisX": {"grid": false, "format": "%b %Y", "labelAngle": 0},
      "axisY": {"domain": false, "grid": true}
    }
  };;
}
```

 View on GitHub

<!-- AGENT NOTE: Do NOT use the legacy syntax below. It is kept only as a reference for charts built before `CustomChartDef`. For any new or edited chart, use the `CustomChartDef` block above. -->

<details>
<summary>Legacy syntax</summary>

```aml
CustomChart {
  fields {
    field date {
      type: "dimension"
      label: "Date field"
    }
    field low {
      type: "dimension"
      label: "Low price"
    }
    field high {
      type: "dimension"
      label: "High price"
    }
    field open {
      type: "dimension"
      label: "Open price"
    }
    field close {
      type: "dimension"
      label: "Close price"
    }
  }

  	options {
		option tooltip {
			type: 'toggle'
			label: 'Show tooltip'
			default_value: true
		}
		option green_candle {
			type: 'color-picker'
			label: 'Green candlestick'
			default_value: 'green'
		}
    option red_candle {
			type: 'color-picker'
			label: 'Red candlestick'
			default_value: 'red'
		}
	}

  template: @vgl
  {
    "data": {
      "values": @{values}
    },
    "layer": [
      {
        "mark": "rule",
        "encoding": {
          "y": {"field": @{fields.low.name}},
          "y2": {"field": @{fields.high.name}}
        }
      },
      {
        "mark": {
          "type": "bar",
          "tooltip": @{options.tooltip.value}
        },
        "encoding": {
          "y": {"field": @{fields.open.name}},
          "y2": {"field": @{fields.close.name}}
        }
      }
    ],
    "encoding": {
      "x": {
        "axis": {
          "format": "%m/%d",
          "labelAngle": -45
        },
        "type": "temporal",
        "field": @{fields.date.name},
      },
      "y": {
        "axis": {
          "title": "Price"
        },
        "type": "quantitative",
        "scale": {
          "zero": false
        }
      },
      "color": {
        "condition": {
          "test": "datum.@{fields.open.name} < datum.@{fields.close.name}",
          "value": @{options.green_candle.value}
        },
        "value": @{options.red_candle.value}
      }
    }
  };;
}
```

</details>

## Required fields

A Candlestick Chart expects exactly five fields. Each row of input is one period (one candle) with its open, high, low, and close values.

| Field   | Label | Type        | Role |
|---------|-------|-------------|------|
| `date`  | Date  | `dimension` | Time period for each candle; sets the x position. Sorted ascending (`apply_order: 1`). |
| `low`   | Low   | `measure`   | Lowest price; bottom of the wick. Sorted ascending (`apply_order: 2`). |
| `high`  | High  | `measure`   | Highest price; top of the wick. Sorted ascending (`apply_order: 3`). |
| `open`  | Open  | `measure`   | Opening price; one end of the candle body. Sorted ascending (`apply_order: 4`). |
| `close` | Close | `measure`   | Closing price; the other end of the candle body. Sorted ascending (`apply_order: 5`). |

**Data requirements:** Pre-aggregate to one row per date; the template does not combine duplicate periods. Each row needs all four price values, and the template colors a candle with the green option when `open` is less than `close` (otherwise the red option).

**Sample data:**

| date       | low    | high   | open   | close  |
|------------|--------|--------|--------|--------|
| 2024-01-02 | 184.30 | 188.44 | 187.15 | 185.64 |
| 2024-01-03 | 183.89 | 185.88 | 184.22 | 184.25 |
| 2024-01-04 | 181.59 | 183.09 | 182.15 | 181.91 |
| 2024-01-05 | 180.17 | 182.76 | 181.99 | 181.18 |
| 2024-01-08 | 181.50 | 185.60 | 182.09 | 185.56 |

## Options

Set these options to adjust the chart without editing the Vega template. The `CustomChartDef` block above declares each option's type and allowed values.

| Option         | Default | Effect |
|----------------|---------|--------|
| `tooltip`      | `true`  | Shows a tooltip on hover over each candle body. |
| `green_candle` | `green` | Fill color for up periods, where `close` is higher than `open`. |
| `red_candle`   | `red`   | Fill color for down periods, where `close` is at or below `open`. |

## Known limitations

- **Every row needs all four price values.** Each candle reads `open`, `high`, `low`, and `close`. Rows missing any of these render incompletely.

- **One row per period.** The template does not aggregate, so duplicate dates draw overlapping candles. Pre-aggregate to a single open-high-low-close row per period.

- **The y-axis does not start at zero.** The scale is set to fit the price range (`zero: false`), which is right for price data but means bar lengths are not proportional to absolute value.