> For the complete documentation index, see [llms.txt](https://docs.labii.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labii.com/widgets/dashboard-widgets/reports/data-driven-charts/chart-by-category-x.md).

# Chart By Category X

## Specs

| Label                     | Value                         |
| ------------------------- | ----------------------------- |
| **Version**               | 1.4.0 (updated on 2026-04-28) |
| **Developer**             | Labii Inc.                    |
| **Type**                  | Dashboard                     |
| **Support Configuration** | Yes                           |

## Overview

The Chart By Category X dashboard widget visualizes record counts or aggregated numeric values across categorical labels on a dashboard. It is designed for situations where laboratory teams need to compare workload, throughput, inventory, status distribution, or other grouped metrics by a category such as project, customer, assay, storage location, or workflow stage. By combining a categorical X axis with optional numeric series and aggregation methods, the widget turns operational table data into a fast, dashboard-friendly comparison chart.

## Use Cases

* **Task tracking**: Show the number of open, overdue, or completed tasks by assignee, project, or status.
* **Customer and project monitoring**: Compare closed deals, completed projects, or submitted requests by customer or business unit.
* **Inventory oversight**: Summarize stock quantity, consumption, or reorder-related metrics by reagent type or storage location.
* **Laboratory operations**: Compare sample counts, test volumes, or batch totals across instruments, sites, or workflow stages.
* **Quality review**: Group deviations, failures, or review outcomes by category to identify patterns quickly.
* **Executive dashboards**: Present high-level grouped KPIs in a compact format that is easy to scan during routine reviews.

## Configuration

This widget supports configuration and works best when your source table includes at least one categorical column for grouping and, when needed, one or more numeric columns for aggregation.

### Initial Setup

{% stepper %}
{% step %}
Open the dashboard where you want to place the widget.
{% endstep %}

{% step %}
Click **Add Widget** and select **Chart By Category X** from the **Data Driven Charts** category.
{% endstep %}

{% step %}
Open the widget settings and select the source **Table**.
{% endstep %}

{% step %}
Choose the **X axis**, optional **Series**, and any filtering or display settings, then click **Save**.
{% endstep %}
{% endstepper %}

### Required Settings

* **Table**: Select the table that contains the records you want to chart.

### Optional Settings

#### Data Requirements

* **Categorical source**: For best results, use a category-style field such as a [Select](/widgets/column-widgets/form/dropdown.md#select) or [ForeignKey](/widgets/column-widgets/form/dropdown.md#foreignkey) column for the X axis.
* **Numeric source for aggregation**: To chart summed or aggregated values instead of counts, use numeric-returning fields such as [Number](/widgets/column-widgets/form/text-inputs.md#number), [Formula](/widgets/column-widgets/calculation.md#formula), or [Consumption](/widgets/column-widgets/calculation/consumption.md).

#### Filtering and Scope

* **Query**: Specify a query to limit the results displayed in the chart.

#### Axis and Series Settings

* **X axis**: Choose the column used for category labels. If nothing is selected, the record name is used.
* **Series**: Choose one or more numeric columns for the data series. If no series is selected, the widget uses total record count by category.

#### Data Aggregation

* **Data aggregation**: Choose how matching values are summarized when a numeric series is selected.
  * **None**: Do not apply an aggregation.
  * **Average**: Use the mean value.
  * **Max**: Use the largest value.
  * **Median**: Use the middle value.
  * **Min**: Use the smallest value.

If no specific series is selected, the widget falls back to count-based output and uses summed count behavior by category.

#### Display Settings

* **Chart title**: Provide the title shown above the chart.
* **Height**: Set chart height in pixels. The default is 250 px.

#### Auto-Update Settings

* **Should auto update**: If checked, the widget performs a live recalculation.
* **Should update when empty**: If checked, the widget performs a live recalculation even when the current result is empty.

{% hint style="info" %}
Use count mode when you want to compare how many records fall into each category. Add one or more numeric series when you need to compare totals or aggregated measurements instead.
{% endhint %}

### Display Configuration

{% stepper %}
{% step %}
Click the widget's **Configure** button after adding it to the dashboard.
{% endstep %}

{% step %}
Set the **Table** and optional **Query** to define the record set.
{% endstep %}

{% step %}
Choose the **X axis**, then optionally add one or more numeric **Series** and a **Data aggregation** method.
{% endstep %}

{% step %}
Set the **Chart title**, **Height**, and any auto-update options, then click **Save**.
{% endstep %}
{% endstepper %}

### Data Source Configuration

Use configuration settings to match the chart to the intended KPI:

{% stepper %}
{% step %}
Select the source **Table**.
{% endstep %}

{% step %}
Apply a **Query** when you need to restrict the chart to a subset such as one project, team, status, instrument, or date-driven cohort.
{% endstep %}

{% step %}
Choose the **X axis** column that defines the categories to compare.
{% endstep %}

{% step %}
Optionally add numeric **Series** and select the aggregation rule that matches the business meaning of the data.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Charts with too many categories are difficult to read on dashboards. Use focused queries and concise category sets to keep the widget legible and fast to load.
{% endhint %}

### Advanced Configuration

{% stepper %}
{% step %}
Use record-count mode when you want a pure distribution chart without additional numeric columns.
{% endstep %}

{% step %}
Switch to numeric series when you need category totals such as total quantity consumed, total revenue, or total completed units.
{% endstep %}

{% step %}
Choose the aggregation rule that matches the analytical question, such as **Average** for performance comparison or **Max** for highest observed values.
{% endstep %}

{% step %}
Enable auto-update on dashboards that monitor frequently changing operational data.
{% endstep %}
{% endstepper %}

## Readonly View

Dashboard widgets display data in read-only mode, and Chart By Category X is optimized for quick comparison across grouped categories.

<figure><img src="/files/UZqYSBmyZdam0OCzSV18" alt="Chart By Category X widget displaying grouped categorical values on a dashboard"><figcaption><p>The widget compares counts or aggregated values across categories for fast dashboard review.</p></figcaption></figure>

### Display Features

* **Categorical comparison chart**: The visualization plots categories on the X axis and count-based or aggregated numeric values on the Y axis.
* **Count or value modes**: The widget can show record counts by category or use selected numeric series for aggregated output.
* **Dashboard-friendly summary**: The chart gives a compact, high-level view of grouped table data without opening list views or reports.
* **Configurable title and size**: The chart title and widget height help fit the visualization into different dashboard layouts.

### Visual Elements

* **X axis categories**: Labels come from the selected category column or from record names when no X axis is set.
* **Series values**: Values reflect either counts or numeric series results.
* **Chart title**: A descriptive title appears above the visualization when configured.
* **Plot area**: The chart area scales to the configured widget height.

### Data Indicators

* **Counts**: When no series is selected, the widget shows how many records belong to each category.
* **Aggregated metrics**: When numeric series are configured, the widget summarizes values according to the selected aggregation rule.
* **Category distribution**: Users can quickly spot which categories are highest, lowest, missing, or unevenly distributed.

### Interactive Features

* **Download**: Export the source data shown by the chart for spreadsheet or presentation use.
* **Live updates**: If auto-update is enabled, the widget recalculates as the underlying data changes.

{% hint style="info" %}
This widget is best for categorical comparisons. If both axes are numeric, use [Chart By Numeric X](/widgets/dashboard-widgets/reports/data-driven-charts/chart-by-numeric-x.md) instead.
{% endhint %}

## Additional Functions

### Count-Based Distribution

You can use the widget without choosing a numeric series. In that mode, it groups records by category and plots the record count for each category.

### Aggregated Numeric Comparison

When one or more numeric series are configured, the widget summarizes category values with the selected aggregation rule. This is useful for comparing totals, averages, maxima, medians, or minima by group.

### Data Export

{% stepper %}
{% step %}
Open the dashboard and locate the **Chart By Category X** widget.
{% endstep %}

{% step %}
Click **Download** to export the currently displayed chart data.
{% endstep %}

{% step %}
Save the file for use in Excel, presentations, or downstream analysis.
{% endstep %}
{% endstepper %}

### Live Monitoring

Enable auto-update when the chart is used on operational dashboards that need to reflect incoming changes without manual refresh.

## Best Practices

### Dashboard Design

* Keep the category list short enough to remain readable in a single dashboard tile.
* Use clear chart titles that explain both the metric and the grouping logic.
* Place this widget near related KPI widgets so users can compare grouped values with totals or trends.

### Data Modeling

* Use stable, well-defined category values to avoid fragmented charts caused by inconsistent labels.
* Prefer categorical columns with limited distinct values for dashboards.
* Use numeric series only when the aggregation meaning is clear to end users.

### Analytical Clarity

* Use record-count mode for workload or distribution questions.
* Use **Average** when comparing typical values by category, and **Max** or **Min** when monitoring extremes.
* Apply focused queries to avoid mixing unrelated records in the same chart.

### Performance and Maintenance

* Avoid very large category sets because they reduce readability and can slow recalculation.
* Review saved queries when table schema or workflow logic changes.
* Use auto-update selectively on high-traffic dashboards.

## Related Widgets

* [Composed Chart By Category X](/widgets/dashboard-widgets/reports/data-driven-charts/composed-chart-by-category-x.md): Use when you need multiple series with different chart types, colors, or Y-axis assignments.
* [Chart By Numeric X](/widgets/dashboard-widgets/reports/data-driven-charts/chart-by-numeric-x.md): Use when both axes should represent numeric values rather than categorical groups.
* [Record Summary](/widgets/dashboard-widgets/reports/record-summary/record-summary.md): Use for broader workspace-level count analysis across projects, tables, and teams.