--- product: "AG Studio" title: "Value Widgets" description: "Show headline numbers in AG Studio with KPI, Multi KPI, radial gauge and linear gauge Widgets: which fields they need, gauge scales and Format settings." framework: react version: "3.1.0" related: - title: "Using the Catalogue" url: "https://www.ag-grid.com/studio/analysts/widget-catalogue/" - title: "Table Widgets" url: "https://www.ag-grid.com/studio/analysts/table-widgets/" - title: "Filter Widgets" url: "https://www.ag-grid.com/studio/analysts/filter-widgets/" - title: "Static Content" url: "https://www.ag-grid.com/studio/analysts/static-content-widgets/" llms: "https://www.ag-grid.com/studio/llms.txt" --- # Value Widgets Value Widgets show aggregated numbers on their own rather than plotting them on a chart. **KPI** displays a single aggregated value prominently, such as a total or the first or last value of a text field, with an optional label beside, above or below it. Use it for totals and headline metrics that need no visual comparison. **Multi KPI** displays a list of aggregated numbers, each with its own label, styled together and arranged in as many columns as you choose. Use it when a handful of related headline figures belong in one place. **Radial Gauge** shows a value against a defined range on a circular dial. Use it for progress or target tracking. **Linear Gauge** shows a value against a range on a horizontal or vertical bar. Use it for progress or threshold indicators. The example below shows a KPI and both gauge types tracking revenue for the year to date, with each gauge's Max set to the annual target. A Multi KPI below them places that revenue alongside the number of orders and new customers. #### Value ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { value: { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "KPI", }, style: { label: { enabled: true, }, }, subtitle: { enabled: true, text: "Revenue year to date", }, }, }, "radial-gauge": { type: "radial-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Radial Gauge", }, subtitle: { enabled: true, text: "Revenue year to date against the annual target", }, style: { scaleLabel: { enabled: true, min: 0, max: 3000000, }, }, }, }, "linear-gauge": { type: "linear-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Linear Gauge", }, subtitle: { enabled: true, text: "Revenue year to date against the annual target", }, style: { scaleLabel: { enabled: true, min: 0, max: 3000000, }, }, }, }, "multi-kpi": { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Multi KPI", }, subtitle: { enabled: true, text: "Year to date", }, style: { columns: 3, label: { position: "below", }, }, }, }, }, widgetLayout: { value: { xTrack: 0, yTrack: 0, xSpan: 8, ySpan: 16, }, "radial-gauge": { xTrack: 8, yTrack: 0, xSpan: 8, ySpan: 16, }, "linear-gauge": { xTrack: 16, yTrack: 0, xSpan: 8, ySpan: 16, }, "multi-kpi": { xTrack: 0, yTrack: 16, xSpan: 24, ySpan: 10, }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Value](https://www.ag-grid.com/studio/examples/value-widgets/value/typescript/) ## Setup ### KPI | Slot | Required | Accepts | What it does | | --- | --- | --- | --- | | Value | Yes | One field | The value to display. A number is aggregated, such as summed. A text field shows its first or last value. | | Sparkline X-Axis | No | One category | Draws a small trend line of the value across the field's values, such as each month. | The sparkline is only drawn for a numeric value. The example below shows a KPI with one numeric field in the Value slot, the same KPI with Month added to the Sparkline X-Axis slot, and a KPI showing the last value of the Month text field. #### KPI Setup ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { "numeric-value": { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Numeric Value", }, style: { label: { enabled: true, }, }, subtitle: { enabled: true, text: "Value: Revenue (Sum)", }, }, }, "sparkline-x-axis": { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], sparklineX: [{ id: "sales.month" }], }, format: { title: { enabled: true, text: "Sparkline X-Axis", }, style: { label: { enabled: true, }, }, subtitle: { enabled: true, text: "Value: Revenue (Sum), Sparkline X-Axis: Month", }, }, }, "text-value": { type: "value", dataMapping: { value: [{ id: "sales.month", aggregation: "last" }], }, format: { title: { enabled: true, text: "Text Value", }, style: { label: { enabled: true, }, }, subtitle: { enabled: true, text: "Value: Month (Last)", }, }, }, }, widgetLayout: { "numeric-value": { xTrack: 0, yTrack: 0, xSpan: 8, ySpan: 14 }, "sparkline-x-axis": { xTrack: 8, yTrack: 0, xSpan: 8, ySpan: 14 }, "text-value": { xTrack: 16, yTrack: 0, xSpan: 8, ySpan: 14 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: KPI Setup](https://www.ag-grid.com/studio/examples/value-widgets/kpi-setup/typescript/) ### Multi KPI | Slot | Required | Accepts | What it does | | --- | --- | --- | --- | | Values | Yes | One or more fields | Adds one tile per field, showing its aggregated value and its name. | You can set how many columns the tiles are arranged in on the Format tab, as shown under [Format](https://www.ag-grid.com/studio/analysts/value-widgets/#format). ### Radial Gauge and Linear Gauge | Slot | Required | Accepts | What it does | | --- | --- | --- | --- | | Value | Yes | One numeric field | The aggregated value the gauge points to. | By default, the gauge's scale runs from 0 to twice the value, so a positive value sits halfway along it. To compare the value with a target, set **Min** and **Max** under **Gauge Scale** on the Format tab. The example below shows each gauge type twice over the same revenue. The left column keeps the default scale, and the right column sets Max to the annual target. #### Gauge Scale ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { "radial-default": { type: "radial-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Radial Gauge: Default Scale", }, subtitle: { enabled: true, text: "Revenue year to date, Min and Max empty", }, }, }, "radial-max": { type: "radial-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Radial Gauge: Max Set", }, subtitle: { enabled: true, text: "Revenue year to date, Gauge Scale > Max 3,000,000", }, style: { scaleLabel: { max: 3000000, }, }, }, }, "linear-default": { type: "linear-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Linear Gauge: Default Scale", }, subtitle: { enabled: true, text: "Revenue year to date, Min and Max empty", }, }, }, "linear-max": { type: "linear-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Linear Gauge: Max Set", }, subtitle: { enabled: true, text: "Revenue year to date, Gauge Scale > Max 3,000,000", }, style: { scaleLabel: { max: 3000000, }, }, }, }, }, widgetLayout: { "radial-default": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 16 }, "radial-max": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 16 }, "linear-default": { xTrack: 0, yTrack: 16, xSpan: 12, ySpan: 16 }, "linear-max": { xTrack: 12, yTrack: 16, xSpan: 12, ySpan: 16 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Gauge Scale](https://www.ag-grid.com/studio/examples/value-widgets/gauge-scale/typescript/) ## Format Value Widgets have these settings of their own on the Format tab, beside the title and appearance settings every Widget has. Your developer can change the defaults shown. ### KPI | Setting | Where | Default | What it does | | --- | --- | --- | --- | | Label | KPI section | Off | Shows a label with the value. It shows the field's name unless you enter your own **Text**. **Position** places it Left of, Above or Below the value, Below by default. | | Font | KPI section | Theme | Sets the font of the value. | | Color | KPI section | Theme | Sets the colour of the value. | | Alignment | KPI section | Left | Aligns the value and label. Justify puts the label at the left edge and the value at the right edge when the label is on the left. In any other case, Justify aligns the same as Left. | | Vertical | KPI section | Center | Places the value at the top, centre or bottom of the Widget. | | Scale to Fit | KPI section | Off | Grows or shrinks the value to fill the space the label and sparkline leave free. | | Type | Sparkline section | Line | Draws the sparkline as a line or as bars. | | Line Weight | Sparkline section | 1 | Sets the thickness of a line sparkline. | | Area Fill | Sparkline section | Off | Fills the area under a line sparkline. | The Sparkline settings apply once a numeric field is in the Value slot and a field is in the Sparkline X-Axis slot. The example below shows each setting turned on in its own KPI, over the same revenue and sparkline. #### KPI Format ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { label: { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], sparklineX: [{ id: "sales.month" }], }, format: { title: { enabled: true, text: "Label", }, subtitle: { enabled: true, text: "KPI > Label on", }, style: { label: { enabled: true, }, }, }, }, "scale-to-fit": { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], sparklineX: [{ id: "sales.month" }], }, format: { title: { enabled: true, text: "Scale to Fit", }, subtitle: { enabled: true, text: "KPI > Scale to Fit on", }, style: { label: { enabled: true, }, textScaling: { enabled: true, }, }, }, }, "bar-sparkline": { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], sparklineX: [{ id: "sales.month" }], }, format: { title: { enabled: true, text: "Bar Sparkline", }, subtitle: { enabled: true, text: "Sparkline > Type Bar", }, style: { label: { enabled: true, }, sparkline: { type: "bar", }, }, }, }, "area-fill": { type: "value", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], sparklineX: [{ id: "sales.month" }], }, format: { title: { enabled: true, text: "Area Fill", }, subtitle: { enabled: true, text: "Sparkline > Area Fill on, Line Weight 2", }, style: { label: { enabled: true, }, sparkline: { areaFill: true, lineWidth: 2, }, }, }, }, }, widgetLayout: { label: { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 14 }, "scale-to-fit": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 14 }, "bar-sparkline": { xTrack: 0, yTrack: 14, xSpan: 12, ySpan: 14 }, "area-fill": { xTrack: 12, yTrack: 14, xSpan: 12, ySpan: 14 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: KPI Format](https://www.ag-grid.com/studio/examples/value-widgets/kpi-format/typescript/) ### Multi KPI | Setting | Where | Default | What it does | | --- | --- | --- | --- | | Font | Multi KPI section | Theme | Sets the font of each tile's value. | | Color | Multi KPI section | Theme | Sets the colour of each tile's value. | | Text Alignment | Multi KPI section | Left | Aligns the value and label within each tile. Justify puts the label at the left edge and the value at the right edge when the label is on the left. In any other case, Justify aligns the same as Left. | | Vertical Alignment | Multi KPI section | Stretch | Places the rows of tiles within the Widget. Stretch grows the rows to fill the Widget's height. Top, Center and Bottom size each tile to its content and place the rows there. | | Columns | Multi KPI section | 1 | Sets the number of columns the tiles are arranged in. | | Row Separator | Multi KPI section | Off | Draws a line between rows of tiles. **Width** and **Color** change the line. | | Column Separator | Multi KPI section | Off | Draws a line between columns of tiles. **Width** and **Color** change the line. | | Label | Multi KPI section | On | Shows each tile's field name as its label. **Position** places it Left of, Above or Below the value, Below by default. **Font** and **Color** change the label's appearance. Turn Label off to hide every label. | The example below shows the same four fields in each Multi KPI. The first keeps the defaults. The others set Columns to 2, and add the settings named in their titles. #### Multi KPI Format ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { "default-layout": { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Default Layout", }, subtitle: { enabled: true, text: "Columns 1, Label Below, Text Alignment Left", }, }, }, columns: { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Columns", }, subtitle: { enabled: true, text: "Columns 2", }, style: { columns: 2, }, }, }, "label-above": { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Label Above", }, subtitle: { enabled: true, text: "Columns 2, Label > Position Above", }, style: { columns: 2, label: { position: "above", }, }, }, }, "text-align-center": { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Text Alignment Center", }, subtitle: { enabled: true, text: "Columns 2, Text Alignment Center", }, style: { columns: 2, textAlign: "center", }, }, }, separators: { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Row and Column Separators", }, subtitle: { enabled: true, text: "Columns 2, Row Separator and Column Separator on", }, style: { columns: 2, rowSeparator: { enabled: true, }, columnSeparator: { enabled: true, }, }, }, }, "label-left-justify": { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Label Left, Justify", }, subtitle: { enabled: true, text: "Columns 2, Label > Position Left, Text Alignment Justify", }, style: { columns: 2, textAlign: "justify", label: { position: "left", }, }, }, }, "label-off": { type: "multi-kpi", dataMapping: { values: [ { id: "sales.revenue", aggregation: "sum" }, { id: "sales.orders", aggregation: "sum" }, { id: "sales.units", aggregation: "sum" }, { id: "sales.new_customers", aggregation: "sum" }, ], }, format: { title: { enabled: true, text: "Label Off", }, subtitle: { enabled: true, text: "Columns 2, Label off", }, style: { columns: 2, label: { enabled: false, }, }, }, }, }, widgetLayout: { "default-layout": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 16 }, columns: { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 16 }, "label-above": { xTrack: 0, yTrack: 16, xSpan: 12, ySpan: 16 }, "text-align-center": { xTrack: 12, yTrack: 16, xSpan: 12, ySpan: 16 }, separators: { xTrack: 0, yTrack: 32, xSpan: 12, ySpan: 16 }, "label-off": { xTrack: 12, yTrack: 32, xSpan: 12, ySpan: 16 }, "label-left-justify": { xTrack: 0, yTrack: 48, xSpan: 24, ySpan: 16 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Multi KPI Format](https://www.ag-grid.com/studio/examples/value-widgets/multi-kpi-format/typescript/) ### Radial Gauge and Linear Gauge | Setting | Where | Default | What it does | | --- | --- | --- | --- | | Min, Max | Radial Gauge or Linear Gauge > Gauge Scale | Empty | Sets the start and end of the scale, in place of 0 and twice the value. | | Value Label | Elements | On | Shows the value on the gauge. On a Linear Gauge, **Placement** positions it, Inside Start by default. | | Scale Label | Elements | On | Shows the numbers along the scale. | | Caption Label | Elements, Radial Gauge only | Off | Shows your own **Text** on the gauge with the value. | | Direction | Linear Gauge section | Vertical | Draws the bar upright or across. | | Thickness | Linear Gauge section | 50 | Sets the thickness of the bar. | The example below shows each setting in its own gauge, all with Max set to the annual target. #### Gauge Format ```ts import { AgReportState, AgStudioApi, AgStudioProperties, createStudio, enableStudioDevValidations, } from "ag-studio"; import { getData } from "./data.ts"; if (process.env.NODE_ENV !== "production") { // Enable extended validations only for development enableStudioDevValidations(); } const initialState: AgReportState = { pages: [ { id: "page1", widgets: { "caption-label": { type: "radial-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Caption Label", }, subtitle: { enabled: true, text: "Max 3,000,000, Elements > Caption Label on", }, style: { scaleLabel: { max: 3000000, }, secondaryLabel: { enabled: true, text: "of annual target", }, }, }, }, "scale-label-off": { type: "radial-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Scale Label Off", }, subtitle: { enabled: true, text: "Max 3,000,000, Elements > Scale Label off", }, style: { scaleLabel: { enabled: false, max: 3000000, }, }, }, }, horizontal: { type: "linear-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Direction: Horizontal", }, subtitle: { enabled: true, text: "Max 3,000,000, Linear Gauge > Direction Horizontal", }, style: { scaleLabel: { max: 3000000, }, direction: "horizontal", }, }, }, thickness: { type: "linear-gauge", dataMapping: { value: [{ id: "sales.revenue", aggregation: "sum" }], }, format: { title: { enabled: true, text: "Thickness", }, subtitle: { enabled: true, text: "Max 3,000,000, Linear Gauge > Thickness 100", }, style: { scaleLabel: { max: 3000000, }, thickness: 100, }, }, }, }, widgetLayout: { "caption-label": { xTrack: 0, yTrack: 0, xSpan: 12, ySpan: 16 }, "scale-label-off": { xTrack: 12, yTrack: 0, xSpan: 12, ySpan: 16 }, horizontal: { xTrack: 0, yTrack: 16, xSpan: 12, ySpan: 16 }, thickness: { xTrack: 12, yTrack: 16, xSpan: 12, ySpan: 16 }, }, }, ], selectedPageId: "page1", panels: { filters: { collapsed: true, }, data: { collapsed: true, }, edit: { collapsed: true, }, }, }; const studioProperties: AgStudioProperties = { mode: "edit", initialState, data: getData(), }; let studioApi: AgStudioApi; // setup Studio after the page has finished loading const studioDiv = document.querySelector("#myStudio")!; studioApi = createStudio(studioDiv, studioProperties); ``` [Live example: Gauge Format](https://www.ag-grid.com/studio/examples/value-widgets/gauge-format/typescript/)