broken aria references when using rgl with quarto

[jfieberg]

Description

When including an interactive rgl plot within a Quarto book using the standard figure syntax (::: {#fig-label} or #| label: fig-), the HTML output generates "Broken ARIA reference" errors in the WAVE accessibility evaluation tool.

Reproducible example

 ---
title: "RGL Accessibility Issue"
format: html
---

## Problematic Figure

The following block generates two "Broken ARIA reference" errors in the WAVE browser extension because the figure container's `aria-labelledby` cannot find a valid target within the rgl widget's HTML structure.

::: {#fig-rgl-test}

```{r}
#| echo: false
#| message: false
library(rgl)
setupKnitr(autoprint = FALSE)

# Basic plot3d call
plot3d(iris$Sepal.Length, iris$Sepal.Width, iris$Petal.Length, 
       col = as.numeric(iris$Species), type = "s", size = 1)

rglwidget()
```

This is an interactive 3D plot that fails accessibility scans.
:::

Ideally, I'd like a way to either:

1. Pass aria attributes directly to the widget through chunk options.
2. Allow the figure container to use role="none" or aria-hidden="true" without being overridden by the Quarto book engine.

Environment:

• Quarto version: Quarto 1.9.36
• R version: 4.5.1 (2025-06-13 ucrt)
• rgl version: Quarto 1.9.36
• OS: Windows 11

Quarto 1.9.36
[>] Checking environment information...
      Quarto cache location: C:\Users\jfieberg\AppData\Local\quarto
[>] Checking versions of quarto binary dependencies...
      Pandoc version 3.8.3: OK
      Dart Sass version 1.87.0: OK
      Deno version 2.4.5: OK
      Typst version 0.14.2: OK
[>] Checking versions of quarto dependencies......OK
[>] Checking Quarto installation......OK
      Version: 1.9.36
      Path: C:\Program Files\RStudio\resources\app\bin\quarto\bin
      CodePage: 1252

[>] Checking tools....................OK
      TinyTeX: (external install)
      Chromium: (not installed)
      Chrome Headless Shell: (not installed)
      VeraPDF: (not installed)

[>] Checking LaTeX....................OK
      Using: TinyTex
      Path: C:\Users\jfieberg\AppData\Roaming\TinyTeX\bin\windows\
      Version: 2025

[>] Checking Chrome Headless....................OK
      Using: Chrome found on system
      Path: C:\Program Files\Google\Chrome\Application\chrome.exe
      Source: Windows Registry

[>] Checking basic markdown render....OK

[>] Checking R installation...........OK
      Version: 4.5.1
      Path: C:/PROGRA~1/R/R-45~1.1
      LibPaths:
        - C:/Users/jfieberg/AppData/Local/R/win-library/4.5
        - C:/Program Files/R/R-4.5.1/library
      knitr: 1.50
      rmarkdown: 2.29

[>] Checking Knitr engine render......OK

[>] Checking Python 3 installation....(None)

      Unable to locate an installed version of Python 3.
      Install Python 3 from https://www.python.org/downloads/

[>] Checking Julia installation...

[mcanouil]

Pass aria attributes directly to the widget through chunk options.

This is for rgl to provide means to do that via knitr.

Allow the figure container to use role="none" or aria-hidden="true" without being overridden by the Quarto book engine.

Add the attributes yourself at the code cell level: https://quarto.org/docs/reference/cells/cells-knitr.html#cell-output

or pass them directly to the cross-ref div {... role="none" ...}

[jfieberg]

Thanks for the suggestions! To be honest, my understanding of these issues is really poor. I tried to follow your second suggestion, using:

::: {#fig-rgl-test role="none"}

but it does not fix the problem. Is that what you were suggesting?

I've also tried things like

::: {#fig-rgl-test aria-hidden="true"}

to no avail. Again, maybe I am misunderstanding how to address this....I am also willing to reach out to the authors of the rgl package if that is likely to be helpful.

[jfieberg]

Just a quick follow up to say that it appears that I can use plotly to create similar (interactive) plots, without the accessibility issues. So, I am going to pursue that option next. Thanks again!

[cderv]

Thanks for the report.

I can confirm the issue and have traced the root cause. The short version: rgl's widget emits aria-labelledby on its outer <div> (and on the <canvas> it adds at runtime) pointing to a sibling element it expects either knitr or Quarto to write — but Quarto's override of knitr's caption-emission code discards that information and never writes the target element. So the two ARIA references resolve to nothing.

This is not specific to the figure container's own aria wiring; that part is fine. The broken references are the ones inside the widget HTML itself.

I've filed #14518 with the full mechanism walk-through and links to the relevant code in rgl, knitr, and Quarto. The fix can live entirely in Quarto's R patch layer — no knitr update needed.

I'll look into the patch on the Quarto side.