From a09255f034772fdebd5ff25cfb26441d8f222e61 Mon Sep 17 00:00:00 2001
From: Test User <test@example.com>
Date: Fri, 6 Feb 2026 02:53:54 -0600
Subject: [PATCH] docs: Add example for aggregating percentage changes in
 DataTable

Adds a new documentation section explaining how to properly aggregate
percentage changes (e.g., growth rates) using weightedMean with a
custom weightCol, rather than a simple average which can be misleading.

Fixes #2592
---
 .../pages/components/data/data-table/index.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/sites/docs/pages/components/data/data-table/index.md b/sites/docs/pages/components/data/data-table/index.md
index dc1f579fdc..5182d585a4 100644
--- a/sites/docs/pages/components/data/data-table/index.md
+++ b/sites/docs/pages/components/data/data-table/index.md
@@ -368,6 +368,25 @@ limit 5
 ```
 </DocTab>
 
+#### Aggregating Percentage Changes
+
+When aggregating percentage changes (e.g., year-over-year growth rates) in a total row, a simple average can be misleading. Instead, use `totalAgg=weightedMean` with a `weightCol` to calculate a properly weighted average.
+
+For example, to aggregate growth rates weighted by the size of each entity (e.g., GDP):
+
+```svelte
+<DataTable data={sales_data} totalRow=true>
+  <Column id=region/>
+  <Column id=revenue fmt=usd/>
+  <Column id=growth_rate 
+          title="Y/Y Growth" 
+          fmt=pct2 
+          totalAgg=weightedMean 
+          weightCol=revenue/>
+</DataTable>
+```
+
+In this example, regions with higher revenue contribute more to the overall growth rate calculation, giving you an accurate weighted average.
 
 
 #### Custom Aggregations Values