> For the complete documentation index, see [llms.txt](https://boxlang.ortusbooks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boxlang.ortusbooks.com/boxlang-framework/modularity/charts/reference/components/bx-chartseries.md).

# ChartSeries

## Summary

Defines a data series within a chart component. This component specifies the chart type, styling options, and data source for one series of data. It must be nested within a `bx:chart` component and can contain `bx:chartdata` components or use query/array data sources.

## Syntax

```xml
<!-- Using chartdata components -->
<bx:chartseries type="pie|bar|line|..." colorlist="red,blue,green" serieslabel="Series Name">
    <bx:chartdata item="Label 1" value="100">
    <bx:chartdata item="Label 2" value="200">
</bx:chartseries>

<!-- Using query data source -->
<bx:chartseries type="bar" query="#myQuery#" itemColumn="category" valueColumn="amount">
</bx:chartseries>

<!-- Using array data source -->
<bx:chartseries type="pie" data="#arrayData#" serieslabel="Sales Data">
</bx:chartseries>
```

## Attributes

| Attribute      | Type   | Required | Default    | Description                                                                                                                                                  |
| -------------- | ------ | -------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`         | string | Yes      | -          | Chart type: `pie`, `bar`, `line`, `doughnut`, `radar`, `polarArea`, `area`, `horizontalbar`, `scatter`, `bubble`                                             |
| `colorlist`    | string | No       | -          | Comma-separated list of colors (hex or named colors) for chart data points. Example: "red,##FF6384,blue"                                                     |
| `serieslabel`  | string | No       | chart type | Label for this data series, used in legends                                                                                                                  |
| `borderColor`  | string | No       | -          | Border color for this series (hex or named color). Overrides chart-level `borderColor`. Not applicable for scatter charts                                    |
| `borderWidth`  | number | No       | -          | Border width in pixels for this series. Not applicable for scatter charts. Overrides chart-level `borderWidth`                                               |
| `borderRadius` | number | No       | -          | Border radius in pixels for this series. Only applicable for bar and horizontalbar charts. Overrides chart-level `borderRadius`                              |
| `query`        | query  | No       | -          | Query object to use as data source. When provided, no child `chartdata` components are required                                                              |
| `itemColumn`   | string | No       | "item"     | Name of the query column containing labels. Used with `query` attribute                                                                                      |
| `valueColumn`  | string | No       | "value"    | Name of the query column containing values. Used with `query` attribute                                                                                      |
| `data`         | array  | No       | -          | Array data source. Can be array of structs `[{item:"x",value:123}]` or array of arrays `[["x",123]]`. For bubble charts use `x`, `y`, `r` instead of `value` |

## Chart Types

### Supported Chart Types

| Type            | Description                         | Best For                                              |
| --------------- | ----------------------------------- | ----------------------------------------------------- |
| `pie`           | Circular chart showing proportions  | Market share, budget allocation, survey results       |
| `bar`           | Vertical bar chart                  | Comparing quantities, showing rankings, temporal data |
| `line`          | Connected data points               | Time series, trend analysis, continuous data          |
| `doughnut`      | Pie chart with hole in center       | Proportions with emphasis on total value              |
| `radar`         | Multivariate data on circular grid  | Comparing multiple variables, skill assessments       |
| `polarArea`     | Pie chart with varying radius       | Proportions where magnitude matters                   |
| `area`          | Line chart with filled area         | Showing volume over time, cumulative data             |
| `horizontalbar` | Horizontal bar chart                | Long category names, rankings                         |
| `scatter`       | X-Y coordinate plot                 | Correlation analysis, distribution patterns           |
| `bubble`        | Three-dimensional data (x, y, size) | Multi-dimensional data analysis, portfolio analysis   |

## Data Sources

### Using ChartData Components

```xml
<bx:chartseries type="pie" colorlist="FF6384,36A2EB,FFCE56">
    <bx:chartdata item="Product A" value="150">
    <bx:chartdata item="Product B" value="200">
    <bx:chartdata item="Product C" value="100">
</bx:chartseries>
```

### Using Query Object

```xml
<bx:chartseries type="bar" 
                query="#getSalesData()#" 
                itemColumn="product_name" 
                valueColumn="total_sales"
                serieslabel="Q4 Sales">
</bx:chartseries>
```

### Using Array of Structs

```xml
<bx:chartseries type="pie"
    data="#[
        {item:'Product A', value:100},
        {item:'Product B', value:200},
        {item:'Product C', value:150}
    ]#"
    serieslabel="Sales Data">
</bx:chartseries>
```

### Using Array of Arrays (Positional)

```xml
<bx:chartseries type="bar"
    data="#[
        ['Product A', 100],
        ['Product B', 200],
        ['Product C', 150]
    ]#"
    serieslabel="Sales Data">
</bx:chartseries>
```

### Bubble Chart Data

For bubble charts, use `x`, `y`, and `r` coordinates:

```xml
<!-- With chartdata components -->
<bx:chartseries type="bubble" serieslabel="Portfolio Analysis">
    <bx:chartdata item="Stock A" x="20" y="15" r="10">
    <bx:chartdata item="Stock B" x="40" y="25" r="15">
</bx:chartseries>

<!-- With array data -->
<bx:chartseries type="bubble"
    data="#[
        {item:'Stock A', x:20, y:15, r:10},
        {item:'Stock B', x:40, y:25, r:15}
    ]#"
    serieslabel="Portfolio Analysis">
</bx:chartseries>
```

## Examples

### Multi-Series Bar Chart

```xml
<bx:chart title="Server Performance" seriesPlacement="cluster">
    <bx:chartseries type="bar" colorlist="##FF6384" serieslabel="CPU Usage">
        <bx:chartdata item="Server 1" value="65">
        <bx:chartdata item="Server 2" value="78">
        <bx:chartdata item="Server 3" value="45">
    </bx:chartseries>
    <bx:chartseries type="bar" colorlist="##36A2EB" serieslabel="Memory Usage">
        <bx:chartdata item="Server 1" value="42">
        <bx:chartdata item="Server 2" value="56">
        <bx:chartdata item="Server 3" value="33">
    </bx:chartseries>
</bx:chart>
```

### Styled Line Chart

```xml
<bx:chartseries type="line" 
                colorlist="##FF6384" 
                serieslabel="Response Time"
                borderColor="##FF6384"
                borderWidth="3">
    <bx:chartdata item="Jan" value="200">
    <bx:chartdata item="Feb" value="180">
    <bx:chartdata item="Mar" value="165">
    <bx:chartdata item="Apr" value="170">
</bx:chartseries>
```

### Query-Based Chart

```xml
<cfquery name="salesQuery" datasource="myDB">
    SELECT product_name as item, SUM(sales_amount) as value
    FROM sales 
    WHERE sale_date >= #CreateDate(2024,1,1)#
    GROUP BY product_name
    ORDER BY value DESC
</cfquery>

<bx:chart title="Product Sales">
    <bx:chartseries type="bar" 
                    query="#salesQuery#" 
                    serieslabel="2024 Sales"
                    colorlist="##36A2EB">
    </bx:chartseries>
</bx:chart>
```

## Notes

* The `type` attribute is required and determines how the data will be visualized
* Color values can be specified as hex codes (with ## prefix) or named colors (red, blue, etc.)
* When using `query` data source, the query must have columns that match `itemColumn` and `valueColumn` values
* For array data sources, use structs for named properties or arrays for positional data
* Border styling attributes at series level override chart-level settings
* Bubble charts require three-dimensional data: x, y coordinates and radius (r)

## Related Components

* [bx:chart](/boxlang-framework/modularity/charts/reference/components/bx-chart.md) - Main chart container component
* [bx:chartdata](/boxlang-framework/modularity/charts/reference/components/bx-chartdata.md) - Individual data point component


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://boxlang.ortusbooks.com/boxlang-framework/modularity/charts/reference/components/bx-chartseries.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.