---
alias: "fc.chart.gauge.wrapper.threshold"
aliases:
  - fc.chart.gauge.wrapper.threshold
category: wrapper
module: Core
---
# fc.chart.gauge.wrapper.threshold

Gauge chart wrapper that converts Metrics API data into a gauge visualization with configurable color thresholds driven by Fluent Settings.

> **Note:** `fc.chart.gauge.md` lists this as an alias. This file documents the wrapper-specific behavior including threshold settings integration. For general gauge chart usage, see `fc.chart.gauge`.

## When to Use
- KPI gauges showing throughput against configurable thresholds
- Sources and Feeds Dashboard performance indicators
- Any Metrics API data that needs gauge visualization with color-coded thresholds

## Key Props
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `dataSource` | string | **Yes** | Path to Metrics API GraphQL data |
| `settingName` | string | **Yes** | Fluent Setting name used to load threshold/color configuration |
| `timeFilterKey` | string | **Yes** | URL parameter name for the current time period filter (scales thresholds) |
| `value` | number/string | No | Template-calculated value or number compared against thresholds |
| `primaryText` | string | No | Large bold text in the center of the gauge |
| `secondaryText` | string | No | Small text displayed below the primary text |
| `colorConfig` | ColorConfig | No | Override default gauge colors |
| `arc` | Arc | No | Gauge arc geometry configuration |
| `chartContainerConfig` | ChartContainerConfig | No | Responsive container sizing |
| `title` | string | No | Chart card title |
| `width` | CardWidth | No | Card width: `"quarter"`, `"third"`, `"half"`, `"two-thirds"`, `"full"`, or 1-12 (default: `"full"`) |
| `noCard` | boolean | No | Render without card background when `true` |

### Arc
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `startAngle` | number | No | Start angle of the first sector (default: `210`) |
| `endAngle` | number | No | End angle of the last sector (default: `-30`) |
| `innerRadius` | number/string | No | Inner radius (default: `"82%"`) |
| `outerRadius` | number/string | No | Outer radius (default: `"93%"`) |
| `cx` | number/string | No | X coordinate of center (default: `"50%"`) |
| `cy` | number/string | No | Y coordinate of center (default: `"50%"`) |

### ColorConfig
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `active` | string / ColorMap | No | Color for the filled (active) sector. HEX string or `[[threshold, color]]` array |
| `inactive` | string / ColorMap | No | Color for the unfilled (inactive) sector. HEX string or `[[threshold, color]]` array |
| `primaryText` | string | No | Color for center primary text (HEX) |
| `secondaryText` | string | No | Color for center secondary text (HEX) |

### ChartContainerConfig
| Prop | Type | Required | What it controls |
|------|------|----------|------------------|
| `width` | string/number | No | Container width (default: `"100%"`) |
| `aspect` | number | No | Width/height ratio (default: `1`) |
| `maxHeight` | number | No | Maximum container height (default: `200`) |
| `height` | string/number | No | Fixed or percentage height |
| `minWidth` | string/number | No | Minimum container width |
| `minHeight` | string/number | No | Minimum container height |

## Data Binding
Transforms Metrics API response data into gauge percentage and color values. The `settingName` prop loads a Fluent Setting containing threshold configuration (an array of `{ percentage, color, threshold }` objects). The `timeFilterKey` reads a URL parameter to scale the per-hour thresholds to the selected time window.

### Setting Format
The Setting referenced by `settingName` must contain a JSON array:
```json
[
  { "percentage": 25, "color": "#D23B3B", "threshold": 0 },
  { "percentage": 75, "color": "#EF8F00", "threshold": 3000 },
  { "percentage": 100, "color": "#4CAF50", "threshold": 4000 }
]
```

## Descendants
No -- self-contained chart component.

## Composition Patterns
- `fc.page` > multiple `fc.chart.gauge.wrapper.threshold` in a row for KPI dashboard
- Place inside `fc.column(width: "quarter")` for compact gauge tiles
- Combine with `fc.daterange.wrapper.forwarder` for time-filtered gauge displays
- Pair with `fc.list.wrapper.source` or `fc.list.wrapper.feed` on the same dashboard

## Gotchas
- `dataSource`, `settingName`, and `timeFilterKey` are all required
- Thresholds in the Setting are per-hour counts -- the component scales them based on the time filter
- `colorConfig.active` can be a simple HEX string or a ColorMap array `[[percentThreshold, color]]` for gradient-like behavior
- Arc angles are in degrees: default spans from 210 to -30 (a standard semi-circular gauge)
- The Setting must exist in the Fluent environment -- missing settings cause the gauge to render with default colors

## Manifest Example
```json
{
  "component": "fc.chart.gauge.wrapper.threshold",
  "props": {
    "title": "Source Throughput",
    "dataSource": "sourceMetrics.totalCount",
    "settingName": "SOURCE_THROUGHPUT_THRESHOLDS",
    "timeFilterKey": "period",
    "primaryText": "{{sourceMetrics.totalCount}}",
    "secondaryText": "items/hr",
    "width": "quarter",
    "arc": {
      "startAngle": 210,
      "endAngle": -30,
      "innerRadius": "82%",
      "outerRadius": "93%"
    }
  }
}
```

## AI Parse Notes
- **Primary intent:** Declarative Mystique component definition for manifests.
- **Selection signals:** Match by `alias`, category, and required `Key Props`.
- **Assembly hints:** Combine with compatible parent/child components listed in `Composition Patterns`.
- **Safety checks:** Validate required props and data bindings before manifest generation.
