# CartesianChart

## Anatomy

[`CartesianChart`](https://api.vico.patrykandpatrick.com/vico/views/com.patrykandpatrick.vico.views.cartesian/-cartesian-chart/) draws a chart based on a Cartesian coordinate plane. The chart includes one or more data layers, drawn by [`CartesianLayer`](https://api.vico.patrykandpatrick.com/vico/views/com.patrykandpatrick.vico.views.cartesian.layer/-cartesian-layer/) instances. Each layer has its own data.

## Ranges

A chart’s *x*- and *y*-ranges depend on those reported by its layers. The *x*-range is the narrowest one that includes all layers’ *x*-ranges. By default, there’s an analogously determined shared *y*-range, but two separate *y*-ranges can also be introduced.

*x*- and *y*-range customization is discussed in [a later subsection](/views/cartesian-charts/cartesianlayer.md#cartesianlayerrangeprovider).

## *x*-step

The *x*-step is a reference *x*-increment. Together with `CartesianLayer` settings, it determines the intrinsic mapping between data and screen units (before zoom). Other components also use it for calibration; for instance, the built-in axis-item placers use it as the default label and line spacing. An *x*-value is considered *major* if it’s a natural number of *x*-steps away from the minimum.

By default, the *x*-step is the greatest common divisor of the differences between consecutive *x*-values the flattened *x*-series. For example, if these *x*-values are $${0, 1, 2, 3}$$, the *x*-step is 1; if the *x* values are $${0, 2, 4, 6}$$, the *x*-step is 2.

To customize the *x*-step, use `CartesianChart`’s `getXStep` constructor parameter, which accepts a `(CartesianChartModel) -> Double` lambda:

```kotlin
CartesianChart(getXStep = { 1.0 }, /* ... */)
```

Consider a daily line chart whose data points may arrive at arbitrary times within a day. Setting the *x*-step to one day means that one day’s worth of *x*-distance intrinsically maps to a specific amount of screen space, and the built-in axis-item placers use a one-day interval.

For a daily column chart that may have gaps in the data, locking the *x*-step to one day causes the chart to leave room for the missing days. Without this, the default would shrink the step based on the data actually present, and columns would be packed together as though no days were missing.

For line charts, both increasing and decreasing the *x*-step relative to the default can be useful. For column and candlestick charts, only increasing it is practical; the opposite could cause overlaps.

Note that the *x*-step is different from zoom. Zoom scales the entire chart—including column widths, for example—whereas the *x*-step changes the logical interpretation of the data’s spacing. The effects described above aren’t achievable with zoom alone.

## Sample charts

* [“Basic column chart”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/BasicColumnChart.kt)
* [“Basic line chart”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/BasicLineChart.kt)
* [“Basic combo chart”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/BasicComboChart.kt)
* [“AI test scores”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/AITestScores.kt)
* [“Daily digital-media use (USA)”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/DailyDigitalMediaUse.kt)
* [“Temperature anomalies (June)”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/TemperatureAnomalies.kt)
* [“Electric-car sales (Norway)”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/ElectricCarSales.kt)
* [“Rock–metal ratios”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/RockMetalRatios.kt)
* [“Gold prices (12/30/2024)”](https://github.com/patrykandpatrick/vico/blob/stable/sample/charts/views/src/main/kotlin/com/patrykandpatrick/vico/sample/charts/views/GoldPrices.kt)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://guide.vico.patrykandpatrick.com/views/cartesian-charts/cartesianchart.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.