adobe / adobe/react-spectrum-charts

New chart type: Gauge (S2)

Open
#770 4 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
127
Forks
29
Avg merge
7d 2h
Merged PRs (30d)
21

Description

### Provide a general summary of the feature here

Add a new **Gauge** chart type to the S2 package (`react-spectrum-charts-s2`). A gauge displays a single prominent value within a defined range, using an arc track with either a needle indicator or a colored fill. It shares characteristics with the Donut and BigNumber chart types.

### 🤔 Expected Behavior?

A `` component is available in the S2 package with the following API:

\`\`\`tsx

\`\`\`

**Full prop list:**

| Prop | Type | Default | Notes |
|------|------|---------|-------|
| `name` | `string` | — | Component identifier, follows standard RSC mark convention |
| `label` | `string` | — | **Required.** Metric name, always shown in center |
| `metric` | `string` | `'value'` | Data key for the current value |
| `minScaleValue` | `number` | `0` | Range minimum, chart-author set |
| `maxScaleValue` | `number` | `100` | Range maximum, chart-author set |
| `method` | `'last' \| 'avg' \| 'sum'` | `'last'` | Data aggregation method |
| `numberFormat` | `NumberFormat` | `'shortNumber'` | d3 format for the displayed value |
| `showNeedle` | `boolean` | `true` | `true` = needle indicator, `false` = colored fill mode |
| `color` | `string` | `'categorical-01'` | Fill/needle color. Ignored when `thresholds` is set |
| `arcSize` | `number` | `2/3` | Arc span as fraction of full circle. `0.2`–`0.85`. Chart-author only |
| `holeRatio` | `number` | `0.8` | Inner radius ratio (track thickness). `0.4`–`0.9`. Chart-author only |
| `thresholds` | `Array<{ value: number; color: string; label?: string }>` | — | Sequential performance zone breakpoints, aligned with Bullet chart API. Breakpoint values auto-shown when labels are set |
| `target` | `string` | — | Data key for the target/goal value (e.g. `'target'`), aligned with Bullet chart API |
| `targetLabel` | `string` | — | Data key for a custom label to display alongside the target marker (e.g. `'goalLabel'`) |
| `ticks` | `'minimal' \| 'normal' \| 'dense'` | — | Decorative tick marks inside arc. Off by default |
| `showRangeLabels` | `boolean` | `false` | Show minScaleValue/maxScaleValue at arc endpoints |
| `size` | `'XL' \| 'L' \| 'M' \| 'S' \| number` | `'M'` | Named sizes: XL=350px, L=225px, M=150px, S=110px |

**Key behaviors:**
- `label` and the formatted value are always shown — they are the primary purpose of the chart
- When `showNeedle: true` (default), `thresholds` colors the arc zones and the needle points to the current value
- When `showNeedle: false`, the arc fills from min to the current value using `color`
- `thresholds` uses sequential breakpoints — no overlapping zones possible
- When a threshold has a `label`, the breakpoint value is automatically shown alongside it
- `target` and `targetLabel` are data keys — values come from the dataset, not hardcoded by the author
- Values outside `minScaleValue`/`maxScaleValue` are clamped silently; a `console.error` is shown for developers
- Accepts `` as a child following standard RSC patterns
- `arcSize` and `holeRatio` are chart-author props — not intended for end-user control
- Track color is fixed to the Spectrum neutral token

### 🔦 Context

Designs are complete in Figma: https://www.figma.com/design/qJ7btj9UJSQPqiiPrrHXmS/S2---Charts---Feedback-Zone?node-id=773-2003

This is intended for the S2 alpha package. There may be prerequisite PRs needed for Donut/BigNumber before the gauge PR is opened.

### 💻 Examples

\`\`\`tsx
// Basic gauge

// With performance zones and data-driven target

\`\`\`

### 🧢 Your Company/Team

AI Assistant

Contributor guide

Open the contributing guide

Research direction

Start in the react-spectrum-charts-s2 package by reviewing the existing Donut and BigNumber chart implementations, standard RSC mark conventions, and ChartTooltip patterns. Use the linked Figma designs and the listed examples to define the Gauge API; it is done when the documented needle and fill modes, thresholds, targets, labels, range handling, sizing, and formatting behaviors are supported.

Written by the indexing model from the issue text.

Assessment

Tech stack
react, typescript
Domain
data-visualization, frontend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
52/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.