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
Copy file name to clipboardExpand all lines: docs/features/interactions.md
+12Lines changed: 12 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -53,6 +53,18 @@ Plot.plot({
53
53
54
54
These values are displayed atop the axes on the edge of the frame; unlike the tip mark, the crosshair mark will not obscure other marks in the plot.
55
55
56
+
When called without data, the crosshair tracks the raw pointer position and inverts the plot's scales directly. This is useful for reading coordinates from any plot, even without matching data.
The [brush mark](../interactions/brush.md) lets the reader select a rectangular region by clicking and dragging. The selected region is then exposed as the plot’s `value` and can be used to filter data. Optionally, when combined with reactive marks — **inactive**, **context**, and **focus** — the brush highlights the selected data while dimming the rest.
Copy file name to clipboardExpand all lines: docs/interactions/crosshair.md
+69-2Lines changed: 69 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -12,6 +12,7 @@ import penguins from "../data/penguins.ts";
12
12
13
13
The **crosshair mark** shows the *x* (horizontal↔︎ position) and *y* (vertical↕︎ position) value of the point closest to the [pointer](./pointer.md) on the bottom and left sides of the frame, respectively.
14
14
15
+
<!-- TODO: add .move() to data-based crosshair, then use it here -->
The crosshair mark does not currently support any format options; values are displayed with the default format. If you are interested in this feature, please upvote [#1596](https://github.com/observablehq/plot/issues/1596). In the meantime, you can implement a custom crosshair using the [pointer transform](./pointer.md) and a [text mark](../marks/text.md).
66
67
68
+
## Dataless crosshair
69
+
70
+
When called without data, the crosshair tracks the raw pointer position and inverts the plot's scales. This is useful when you want a crosshair on any plot — even one without data that matches the crosshair's position channels — or when you want to read coordinates directly from the scales.
In the future, displayed values will be automatically rounded to the coarsest precision that still distinguishes neighboring pixels.
88
+
89
+
## Input events
90
+
91
+
The crosshair dispatches [*input* events](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/input_event) when the pointer moves. The plot's value (`plot.value`) is set to an object with **x** and **y** properties (the scale-inverted values), or null when the pointer leaves the frame.
92
+
93
+
```js
94
+
constch=Plot.crosshair();
95
+
constplot=ch.plot({
96
+
x: {domain: [0, 100]},
97
+
y: {domain: [0, 100]},
98
+
marks: [Plot.frame()]
99
+
});
100
+
101
+
plot.addEventListener("input", () => {
102
+
console.log(plot.value); // {x: 42, y: 73} or null
103
+
});
104
+
```
105
+
106
+
For faceted plots, the value also includes **fx** and **fy** when applicable.
Returns a new crosshair for the given *data* and *options*, drawing horizontal and vertical rules. The corresponding **x** and **y** values are also drawn just outside the bottom and left sides of the frame, respectively, typically on top of the axes. If either **x** or **y** is not specified, the crosshair will be one-dimensional.
94
135
136
+
## crosshair(*options*) {#crosshair-dataless}
137
+
138
+
```js
139
+
Plot.crosshair()
140
+
```
141
+
142
+
When called without data, returns a dataless crosshair that tracks the raw pointer position and inverts the plot's scales. The returned mark has a [move](#crosshair-move) method for programmatic control.
143
+
95
144
## crosshairX(*data*, *options*) {#crosshairX}
96
145
97
146
```js
98
147
Plot.crosshairX(aapl, {x:"Date", y:"Close"})
99
148
```
100
149
101
-
Like crosshair, but using [pointerX](./pointer.md#pointerX) when *x* is the dominant dimension, like time in a time-series chart.
150
+
Like crosshair, but using [pointerX](./pointer.md#pointerX) when *x* is the dominant dimension, like time in a time-series chart. When called without data, returns a dataless crosshair restricted to the *x* dimension.
102
151
103
152
## crosshairY(*data*, *options*) {#crosshairY}
104
153
105
154
```js
106
155
Plot.crosshairY(aapl, {x:"Date", y:"Close"})
107
156
```
108
157
109
-
Like crosshair, but using [pointerY](./pointer.md#pointerY) when *y* is the dominant dimension.
158
+
Like crosshair, but using [pointerY](./pointer.md#pointerY) when *y* is the dominant dimension. When called without data, returns a dataless crosshair restricted to the *y* dimension.
159
+
160
+
## *crosshair*.move(*value*) {#crosshair-move}
161
+
162
+
```js
163
+
ch.move({x:newDate("2020-06-01"), y:42})
164
+
```
165
+
166
+
Programmatically sets the crosshair position in data space. Pass an object with **x** and/or **y** values to show the crosshair at that position, or null to hide it. The plot dispatches an *input* event, just as if the user had moved the pointer.
167
+
168
+
```js
169
+
ch.move(null) // hide
170
+
```
171
+
172
+
For faceted plots, include **fx** or **fy** to target a specific facet:
0 commit comments