You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Legends (new CircleLegend and GeoLegend) and value indicator (tooltip, explicit) (#818)
* feat(CircleLegend): New component for visualizing radius (`rScale`) values as nested circles
* update catalog and screenshots
* feat(GeoLegend): New scale-bar legend showing real-world distance for the current `Chart` projection
* update catalog and screenshots
* Update bubble-map to use integrated cScale and rScale, and use data-driven Circle
* feat(Legend, CircleLegend): Show an indicator of the current tooltip value on the legend
feat(CircleLegend): New component for visualizing radius (`rScale`) values as nested circles
6
+
7
+
`CircleLegend` displays a set of bottom-aligned nested circles representing values from a radius scale, useful alongside bubble maps and scatter charts that encode magnitude via circle area. By default it reads `rScale` from the chart context, but a `scale` prop can also be passed to render standalone.
8
+
9
+
Supports `tickValues` / `ticks` / `tickFormat` for value selection and formatting, a `title` rendered centered above the circles, and `labelPlacement="right" | "left" | "inline"` to render tick labels with a leader line on either side of the circles or centered inside each circle near the top.
feat(GeoLegend): New scale-bar legend showing real-world distance for the current `Chart` projection
6
+
7
+
`GeoLegend` reads the active geo projection from the chart context and renders a labeled scale bar with tick subdivisions. By default it picks a "nice" round distance that covers ~25% of the chart width, but `distance` can be passed for an explicit value. Supports `units="km" | "mi"`, configurable `ticks`, `tickFormat`, `title`, and the standard `placement` props. Inspired by Harry Stevens' [d3-geo-scale-bar](https://observablehq.com/@harrystevens/introducing-d3-geo-scale-bar).
feat(Legend, CircleLegend): Show an indicator of the current tooltip value on the legend
6
+
7
+
`Legend` (ramp variant) now draws a small upward-pointing arrow below the color ramp at the position of the currently hovered value, and `CircleLegend` draws a 50%-opacity filled circle at the corresponding radius. Both auto-read the hovered data from `ctx.tooltip.data` and pipe it through the chart's color (`ctx.c`) / radius (`ctx.r`) accessors, so wiring is automatic for charts that configure `c` / `r` / `cScale` / `rScale` via `Chart` props.
8
+
9
+
A new `value` prop on both components allows explicitly setting the indicator value (overriding the auto-detection), useful when the tooltip data shape doesn't match the chart's accessor.
10
+
11
+
For `scaleThreshold` / `scaleQuantize` / `scaleQuantile` scales, the `Legend` indicator centers on the matching bucket swatch.
description: Nested-circle legend used to communicate values encoded by circle radius (typically `Chart` `rScale`). Inspired by Harry Stevens' Observable circle legend.
`CircleLegend` works with any continuous d3 scale. `scaleSqrt` is the most common choice since it makes circle _area_ proportional to the value, but `scaleLinear`, `scaleLog` (strictly positive domains), and `scalePow` are also supported.
15
+
16
+
:example{name="scale-types"showCode}
17
+
18
+
### Label placement
19
+
20
+
Use `labelPlacement` to control where tick labels are rendered. `'right'` (default) and `'left'` render labels outside the circles with leader lines, while `'inline'` centers each label inside its circle near the top.
21
+
22
+
:example{name="label-placement"showCode}
23
+
24
+
### Tooltip indicator
25
+
26
+
When the chart has an active tooltip, `CircleLegend` draws a 50%-opacity filled circle at the current hovered value's radius, overlaid on the nested circles. By default it reads `ctx.tooltip.data` and pipes it through the chart's radius accessor (`ctx.r`), so charts that configure `r` / `rScale` on `<Chart>` get the indicator automatically.
27
+
28
+
Pass an explicit `value` prop to override the auto-detection when the tooltip data shape doesn't match the chart's radius accessor:
description: Geographic scale bar showing real-world distance for the current `Chart` projection. Inspired by Harry Stevens' d3-geo-scale-bar.
3
+
category: geo
4
+
layers: [html]
5
+
related: [Legend, CircleLegend]
6
+
---
7
+
8
+
## Usage
9
+
10
+
`GeoLegend` reads the active geo projection from the chart context and computes a "nice" round distance that fits within the chart, drawing a labeled scale bar with tick subdivisions. Pass `units="mi"` to display miles instead of the default kilometers, or set `distance` for an explicit value.
11
+
12
+
The bar reactively updates as the user pans/zooms — both `transform.mode: 'canvas'` and `transform.mode: 'projection'` are supported.
13
+
14
+
### Projection transform mode
15
+
16
+
:example{name="basic"showCode}
17
+
18
+
### Canvas transform mode
19
+
20
+
:example{name="canvas-mode"showCode}
21
+
22
+
### Variants
23
+
24
+
`variant` controls the visual style of the bar: `'bracket'` (default — top rule with downward tick brackets) or `'alternating'` (filled/unfilled segments between ticks).
25
+
26
+
:example{name="variants"showCode}
27
+
28
+
### Ticks
29
+
30
+
Use `ticks` to control the number of subdivisions. Set `ticks={1}` to show only the endpoints (`0` and the final value).
31
+
32
+
:example{name="ticks"showCode}
33
+
34
+
### Tick format
35
+
36
+
`tickFormat` accepts any [`@layerstack/utils`](https://github.com/techniq/layerstack/tree/main/packages/utils) format key (e.g. `"metric"`, `"integer"`), a `FormatConfig` object, or a custom `(value) => string` function. The default appends the unit on the last tick only.
37
+
38
+
:example{name="tick-format"showCode}
39
+
40
+
### Stacked units
41
+
42
+
Use `labelPlacement="top"` to place labels above the bar so two legends with different units (e.g. kilometers and miles) can be stacked tightly with their bars touching.
43
+
44
+
:example{name="stacked-units"showCode}
45
+
46
+
## Reference point
47
+
48
+
The pixels-per-unit ratio is measured at a single reference point on the projection — by default, the center of the chart's plot area (`[width / 2, height / 2]`). For conformal projections like Mercator where scale varies with latitude, the legend is only accurate at that reference point. Pass an explicit `referencePoint` in chart pixel coordinates to anchor the measurement elsewhere (e.g. near the legend itself, or over your region of interest).
Copy file name to clipboardExpand all lines: docs/src/content/components/Legend.md
+19-2Lines changed: 19 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,14 +1,31 @@
1
1
---
2
-
description: Commonly used component which explains the symbols, colors, or patterns used in a chart, helping interpret the represented data categories. Filtering and toggling visibility of data series can be enabled for interactivity.
2
+
description: Commonly used component which explains the symbols, colors, or patterns used in a chart, helping interpret the represented data categories. Typically paired with `Chart` `cScale` (color scale). Filtering and toggling visibility of data series can be enabled for interactivity.
3
3
category: common
4
4
layers: [html]
5
-
related: []
5
+
related: [CircleLegend, GeoLegend]
6
6
---
7
7
8
8
## Usage
9
9
10
10
:example{name="sequential"showCode}
11
11
12
+
### Tooltip indicator
13
+
14
+
When the chart has an active tooltip, `Legend` draws a small arrow below the color ramp at the position of the currently hovered value. By default it reads `ctx.tooltip.data` and pipes it through the chart's color accessor (`ctx.c`), so charts that configure `c` / `cScale` on `<Chart>` get the indicator automatically.
15
+
16
+
For `scaleThreshold` / `scaleQuantize` / `scaleQuantile` scales, the arrow centers on the matching bucket swatch.
17
+
18
+
Pass an explicit `value` prop to override the auto-detection — useful when the tooltip data shape doesn't match the chart's color accessor:
0 commit comments