feat: add linked parameter to opts_hover() and opts_selection()

davidgohel · davidgohel · commit 613d590ac1af · 2026-02-06T16:31:31.000+01:00
- Share hover/selection state between geometry (data-id) and legend (key-id) elements. - Added linked_scale Shiny example to demonstrate the feature. see #330
diff --git a/DESCRIPTION b/DESCRIPTION
@@ -1,7 +1,7 @@
 Type: Package
 Package: ggiraph
 Title: Make 'ggplot2' Graphics Interactive
-Version: 0.9.5.002
+Version: 0.9.5.003
 Authors@R: c(
     person("David", "Gohel", , "david.gohel@ardata.fr", role = c("aut", "cre")),
     person("Panagiotis", "Skintzos", , "sigmapi@posteo.net", role = "aut"),
diff --git a/NEWS.md b/NEWS.md
@@ -1,5 +1,13 @@
 # ggiraph 0.9.5
 
+## Feature
+
+- `opts_hover()` and `opts_selection()` gain a new `linked` parameter. When
+`linked = TRUE`, hover and selection states are shared between geometry
+elements (`data-id`) and legend/guide elements (`key-id`): hovering or
+clicking a legend key highlights or selects the corresponding geometries,
+and vice versa (#330).
+
 ## Issues
 
 - fix label_interactive broken by the new V4 ggplot2 (#348)
diff --git a/R/girafe_options.R b/R/girafe_options.R
@@ -167,6 +167,8 @@ opts_tooltip <- function(
 #' By default (`NULL`) it's set to `Infinity` which means that there is no distance limit.
 #' Setting it to 50, for example, it will hover the nearest element that has
 #' at maximum 50 SVG units (pixels) distance from the mouse cursor.
+#' @param linked if TRUE, hovering a legend/guide element (`key-id`) will
+#' also highlight the corresponding geometry elements (`data-id`) and vice versa.
 #' @note **IMPORTANT**: When applying a `fill` style with the `css` argument,
 #' be aware that the browser's CSS engine will apply it also to line elements,
 #' if there are any that use the hovering feature. This will cause an undesired effect.
@@ -192,7 +194,7 @@ opts_tooltip <- function(
 #' @export
 #' @family girafe animation options
 #' @seealso [girafe_css()], [girafe_css_bicolor()]
-opts_hover <- function(css = NULL, reactive = FALSE, nearest_distance = NULL) {
+opts_hover <- function(css = NULL, reactive = FALSE, nearest_distance = NULL, linked = FALSE) {
   css <- check_css(
     css,
     default = "fill:orange;stroke:gray;",
@@ -211,8 +213,11 @@ opts_hover <- function(css = NULL, reactive = FALSE, nearest_distance = NULL) {
       call. = FALSE
     )
   }
+  if (!is_valid_logical(linked)) {
+    abort("`linked` must be a scalar logical", call = NULL)
+  }
 
-  x <- list(css = css, reactive = reactive, nearest_distance = nearest_distance)
+  x <- list(css = css, reactive = reactive, nearest_distance = nearest_distance, linked = linked)
   class(x) <- "opts_hover"
   attr(x, "explicit_args") <- names(match.call())[-1]
   x
@@ -292,6 +297,8 @@ opts_hover_theme <- function(css = NULL, reactive = FALSE) {
 #' documentation examples or R Markdown output).
 #' @param selected character vector, id to be selected when the graph will be
 #' initialized.
+#' @param linked if TRUE, selecting a legend/guide element (`key-id`) will
+#' also select the corresponding geometry elements (`data-id`) and vice versa.
 #' @note **IMPORTANT**: When applying a `fill` style with the `css` argument,
 #' be aware that the browser's CSS engine will apply it also to line elements,
 #' if there are any that use the selection feature. This will cause an undesired effect.
@@ -322,7 +329,8 @@ opts_selection <- function(
   css = NULL,
   type = c("multiple", "single", "none"),
   only_shiny = TRUE,
-  selected = character(0)
+  selected = character(0),
+  linked = FALSE
 ) {
   css <- check_css(
     css,
@@ -334,12 +342,16 @@ opts_selection <- function(
   if (!is_valid_logical(only_shiny)) {
     abort("`only_shiny` must be a scalar logical", call = NULL)
   }
+  if (!is_valid_logical(linked)) {
+    abort("`linked` must be a scalar logical", call = NULL)
+  }
 
   x <- list(
     css = css,
     type = type,
     only_shiny = only_shiny,
-    selected = as.character(selected)
+    selected = as.character(selected),
+    linked = linked
   )
   class(x) <- "opts_selection"
   attr(x, "explicit_args") <- names(match.call())[-1]
diff --git a/inst/examples/shiny/linked_scale/DESCRIPTION b/inst/examples/shiny/linked_scale/DESCRIPTION
@@ -0,0 +1,7 @@
+Title: Interactive legend
+Author: David Gohel
+AuthorUrl: https://www.ardata.fr
+License: GPL-3
+DisplayMode: Showcase
+Tags: reactive-selection
+Type: Shiny
diff --git a/inst/examples/shiny/linked_scale/Readme.md b/inst/examples/shiny/linked_scale/Readme.md
@@ -0,0 +1,6 @@
+Shiny application for linked interactive legend
+
+Hover and selection are linked between legend keys and geometry points using
+`opts_hover(linked = TRUE)` and `opts_selection(linked = TRUE)`.
+Clicking a legend key selects the corresponding points and vice versa.
+A summary of the selection is rendered.
diff --git a/inst/examples/shiny/linked_scale/server.R b/inst/examples/shiny/linked_scale/server.R
@@ -0,0 +1,48 @@
+library(ggplot2)
+library(ggiraph)
+
+gg <- ggplot(iris, aes(x = Sepal.Length, y = Sepal.Width,
+                       color = Species, data_id = Species)) +
+  geom_point_interactive(size = 3) +
+  theme_minimal() +
+  scale_colour_manual_interactive(
+    data_id = c("setosa" = "setosa", "versicolor" = "versicolor", "virginica" = "virginica"),
+    tooltip = c("setosa" = "setosa", "versicolor" = "versicolor", "virginica" = "virginica"),
+    values = c("setosa" = "#E41A1C", "versicolor" = "#377EB8", "virginica" = "#4DAF4A")) +
+  theme(legend.position = "top")
+
+
+shinyServer(function(input, output, session) {
+
+  selected_keys <- reactive({
+    input$plot_key_selected
+  })
+
+  output$plot <- renderGirafe({
+    x <- girafe(
+      code = print(gg), width_svg = 5, height_svg = 5,
+      options = list(
+        opts_toolbar(saveaspng = FALSE),
+        opts_selection(type = "single", linked = TRUE),
+        opts_selection_key(css = "stroke:black;r:5pt;"),
+        opts_hover(css = "fill:wheat;stroke:black;stroke-width:3px;cursor:pointer;",
+                   linked = TRUE),
+        opts_hover_key(css = "stroke:black;r:5pt;cursor:pointer;")
+      )
+    )
+    x
+  })
+
+  output$datatab <- renderTable({
+    out <- iris[iris$Species %in% selected_keys(), -5]
+    if( nrow(out) < 1 ) return(NULL)
+    row.names(out) <- NULL
+    data.frame( variable = colnames(out),
+                min = apply(out, 2, min),
+                mean = colMeans(out),
+                sd = apply(out, 2, sd),
+                max = apply(out, 2, max)
+                )
+  })
+
+})
diff --git a/inst/examples/shiny/linked_scale/ui.R b/inst/examples/shiny/linked_scale/ui.R
@@ -0,0 +1,17 @@
+library(ggiraph)
+
+shinyUI(fluidPage(
+  tags$h1("ggiraph key selection demo"),
+
+  fluidRow(
+    column(width = 7,
+           h4("Click a legend key or a point to select: "),
+           girafeOutput("plot")
+    ),
+    column(width = 5,
+           h4("Selection summary"),
+           tableOutput("datatab")
+    )
+    )
+  )
+)
diff --git a/inst/htmlwidgets/girafe.js b/inst/htmlwidgets/girafe.js
diff --git a/man/opts_hover.Rd b/man/opts_hover.Rd
diff --git a/man/opts_selection.Rd b/man/opts_selection.Rd
diff --git a/srcjs/modules/hover.js b/srcjs/modules/hover.js
@@ -13,6 +13,7 @@ export default class HoverHandler {
     this.nodeIds = [];
     this.dataHovered = [];
     this.lastTargetId = null;
+    this.linkedHandlers = null;
   }
 
   init() {
@@ -72,6 +73,14 @@ export default class HoverHandler {
       this.lastTargetId = null;
       this.setHovered([]);
     }
+    if (this.linkedHandlers) {
+      this.linkedHandlers.forEach((h) => {
+        if (h.lastTargetId) {
+          h.lastTargetId = null;
+          h.setHovered([], true);
+        }
+      });
+    }
   }
 
   isValidTarget(target) {
@@ -97,7 +106,7 @@ export default class HoverHandler {
     return false;
   }
 
-  setHovered(hovered) {
+  setHovered(hovered, fromLinked = false) {
     if (
       this.dataHovered.length !== hovered.length ||
       !this.dataHovered.every((item) => hovered.includes(item))
@@ -107,6 +116,9 @@ export default class HoverHandler {
       if (this.shinyInputId) {
         Shiny.onInputChange(this.shinyInputId, this.dataHovered);
       }
+      if (!fromLinked && this.linkedHandlers) {
+        this.linkedHandlers.forEach((h) => h.setHovered(hovered, true));
+      }
     }
   }
 
diff --git a/srcjs/modules/selection.js b/srcjs/modules/selection.js
@@ -15,6 +15,7 @@ export default class SelectionHandler {
     this.initialSelection = options.selected;
     this.nodeIds = [];
     this.dataSelected = [];
+    this.linkedHandlers = null;
   }
 
   init() {
@@ -111,6 +112,9 @@ export default class SelectionHandler {
 
   clear() {
     this.setSelected([]);
+    if (this.linkedHandlers) {
+      this.linkedHandlers.forEach((h) => h.setSelected([], true));
+    }
   }
 
   isValidTarget(target) {
@@ -149,7 +153,7 @@ export default class SelectionHandler {
     return false;
   }
 
-  setSelected(selected) {
+  setSelected(selected, fromLinked = false) {
     if (
       this.dataSelected.length !== selected.length ||
       !this.dataSelected.every((item) => selected.includes(item))
@@ -159,6 +163,9 @@ export default class SelectionHandler {
       if (this.shinyInputId) {
         Shiny.onInputChange(this.shinyInputId, this.dataSelected);
       }
+      if (!fromLinked && this.linkedHandlers) {
+        this.linkedHandlers.forEach((h) => h.setSelected(selected, true));
+      }
     }
   }
 
diff --git a/srcjs/modules/svg.js b/srcjs/modules/svg.js
@@ -156,6 +156,15 @@ export default class SVGObject {
     } catch (e) {
       console.error(e);
     }
+    // link hover_data and hover_key handlers
+    if (hover.linked) {
+      const hd = this.handlers.get('hover_data');
+      const hk = this.handlers.get('hover_key');
+      if (hd && hk) {
+        hd.linkedHandlers = [hk];
+        hk.linkedHandlers = [hd];
+      }
+    }
   }
 
   setupSelection(select, select_inv, select_key, select_theme) {
@@ -194,6 +203,15 @@ export default class SVGObject {
     } catch (e) {
       console.error(e);
     }
+    // link select_data and select_key handlers
+    if (select.linked) {
+      const sd = this.handlers.get('select_data');
+      const sk = this.handlers.get('select_key');
+      if (sd && sk) {
+        sd.linkedHandlers = [sk];
+        sk.linkedHandlers = [sd];
+      }
+    }
   }
 
   setupMouse() {
