Skip to content

The easy-to-use open source Business Intelligence and Embedded Analytics tool that lets everyone work with data :bar_chart:

Custom viz: document formatValue column caveat (#84606)

Egor Grushinda2269512edb
diff --git a/docs/developers-guide/custom-visualizations.md b/docs/developers-guide/custom-visualizations.md
index 429fc480674..da9446ecbc9 100644
--- a/docs/developers-guide/custom-visualizations.md
+++ b/docs/developers-guide/custom-visualizations.md
@@ -345,9 +345,11 @@ Render numbers, dates, and currencies the way the rest of Metabase does with `fo
import { formatValue } from "@metabase/custom-viz";
formatValue(row[1], { column: cols[1] });
-formatValue(0.084, { number_style: "percent", decimals: 1 }); // "8.4%"
+formatValue(row[1], { column: cols[1], number_style: "percent", decimals: 1 });
```
+Metabase picks the formatting by the column's type, so number options only take effect together with a numeric `column`. Without one, a number is rendered as is (`prefix` and `suffix` still apply). If a number doesn't come from a column, you may want to pass the column it's derived from.
+
To honor the formatting people pick in the column formatting popover (the one `showColumnSetting: true` enables on `"field"` and `"fields"` widgets - see [built-in widgets](#built-in-widgets)), format with `settings.column(col)`. It resolves a column's effective settings (instance-wide defaults, the column's metadata settings, and the card-level popover settings, merged in that order) into ready-to-use `formatValue` options:
```tsx
diff --git a/enterprise/frontend/src/custom-viz/src/types/format.ts b/enterprise/frontend/src/custom-viz/src/types/format.ts
index 4634b0fa8c8..41106c96756 100644
--- a/enterprise/frontend/src/custom-viz/src/types/format.ts
+++ b/enterprise/frontend/src/custom-viz/src/types/format.ts
@@ -1,6 +1,10 @@
import type { Column, RowValue } from "./data";
export type FormatValueOptions = {
+ /**
+ * Formatting is picked by the column's type, so number options like
+ * `number_style` and `decimals` have no effect without a numeric column.
+ */
column?: Column;
compact?: boolean;
currency?: string;