Skip to contents

maidr

Overview

maidr (Multimodal Access and Interactive Data Representation) makes data visualizations accessible to users with visual impairments. It converts ggplot2 and Base R plots, and experimentally lattice charts, into interactive, accessible HTML/SVG formats with keyboard navigation, screen reader support, and sonification. maidr for R is the R binding of MAIDR, the JavaScript core developed by the (x)Ability Design Lab at the University of Illinois Urbana-Champaign; the same accessibility layer is available for Python as py-maidr.

The package provides two main functions:

  • show() displays an interactive accessible plot in RStudio Viewer or browser
  • save_html() writes a plot to an HTML file, with the MAIDR.js library in a lib/ folder beside it

Installation

maidr requires R 4.0.0 or later. Install the stable release from CRAN:

Or install the development version from GitHub:

# Using pak (recommended)
pak::pak("xability/r-maidr")

# Alternative: using pacman (auto-installs if missing)
pacman::p_load_gh("xability/r-maidr")

The development version is built from source, and maidr includes C++ code, so this needs a compiler: Rtools on Windows, the Xcode command line tools on macOS.

Usage

ggplot2 

library(maidr)
library(ggplot2)

p <- ggplot(mpg, aes(x = class)) +
  geom_bar(fill = "steelblue") +
  labs(title = "Vehicle Classes", x = "Class", y = "Count")

# Display interactive accessible plot
show(p)

# Or save to file
save_html(p, "vehicle_classes.html")

Base R 

library(maidr)

# Create plot first
barplot(
  table(mtcars$cyl),
  main = "Cars by Cylinder Count",
  xlab = "Cylinders",
  ylab = "Count"
)

# Then call show() without arguments
show()

plotly, highcharter and echarts4r widgets

maidr_htmlwidget() makes an interactive chart from plotly (plot_ly(), ggplotly()), highcharter or echarts4r accessible. The chart is read in the browser by the MAIDR adapter for the library that draws it, so it works wherever the widget does: the viewer, htmlwidgets::saveWidget(), R Markdown, Quarto and Shiny.

library(maidr)
library(plotly)

plot_ly(mtcars, x = ~wt, y = ~mpg, type = "scatter", mode = "markers") |>
  maidr_htmlwidget()

# ggplotly() keeps your ggplot2 code
ggplotly(ggplot(mtcars, aes(wt, mpg)) + geom_point()) |>
  maidr_htmlwidget()

An echarts4r chart is switched to ECharts’ SVG renderer, which MAIDR needs to highlight the mark being read. While an echarts4r chart shows its legend, the visual highlight is off; audio, text and braille are not affected.

An echarts4r fan chart – a median line with bands drawn as stacked areas – is read as a percentile band once percentile_bands names its series and the quantiles of each band’s edges. The option needs maidr.js 4.15.0 or later, which use_cdn = TRUE loads; with the bundled 4.14.0 it is ignored with a warning. See ?maidr_htmlwidget.

fan |>
  e_charts(week) |>                    # a category x axis
  e_line(median, name = "Median") |>
  e_line(lower, stack = "band", name = "lower", symbol = "none",
         lineStyle = list(opacity = 0)) |>
  e_area(width, stack = "band", name = "90% interval", symbol = "none") |>
  maidr_htmlwidget(
    use_cdn = TRUE,
    percentile_bands = list(
      median = "Median",
      bands = data.frame(series = "90% interval", lower = 0.05, upper = 0.95)
    )
  )

lattice

A lattice chart is used the way a ggplot2 object is: printing it opens the maidr viewer, and show() and save_html() take it. Every lattice chart type maidr reads is experimental; the lattice table under Experimental Plot Types lists them.

library(maidr)
library(lattice)

cylinders <- as.data.frame(table(Cylinders = mtcars$cyl))

p <- barchart(
  Freq ~ Cylinders,
  data = cylinders,
  origin = 0,
  main = "Cars by Cylinder Count",
  ylab = "Count"
)

# Printing the chart opens it in the maidr viewer
p

# show() is the explicit form; save_html() writes it to a file
show(p)
save_html(p, "cylinders.html")

A conditioned chart, such as xyplot(mpg ~ wt | factor(cyl), mtcars), is read one panel at a time: each panel is a subplot of its own, named after its strip.

Chart size

A chart is drawn at 7 x 5 inches unless you give it a size, in inches as ggplot2::ggsave() takes one, and its SVG is 72 pixels to the inch. The size is the room the chart is laid out in; the data, titles and axis labels a reader hears are the same at every size. Only a lattice chart conditioned on one variable with no layout = changes for a reader: lattice arranges its panels for the shape of the page, and the order a reader moves through them follows, so give it layout = to keep one. A side over 50 in is refused, as ggsave() refuses one, since it is most likely pixels.

show(p, width = 10, height = 4)
save_html(p, "wide.html", width = 10, height = 4)

# Base R: draw, then show at a size
barplot(table(mtcars$cyl))
show(width = 6, height = 4)

# Shiny: the chart's size; maidr_output()'s width and height size the output
output$plot <- render_maidr(p, fig_width = 10, fig_height = 4)

In R Markdown and Quarto the chunk’s fig.width and fig.height set it. Nothing else does: not the device a Base R chart was drawn on, nor the window or Shiny output a chart is shown in, which shrinks a wider chart to fit. A candlestick chart is never drawn smaller than 12 x 6 in; asked for less (in a document, by the chunk’s own options), maidr says in a message the size it used. A Base R chart too small for its margins and text, or for the cells a layout() sizes with lcm(), at the size you ask for is an error naming the size. With no size asked for, one too small for 7 x 5 in, such as a par(mfrow) grid of five rows, is drawn larger, at 7 x 7 in or the smallest larger size that leaves each of its plots room to be seen, and a message names the size.

R Markdown and Quarto

library(maidr) in a setup chunk is all a document needs. Every plot it draws, with ggplot2, lattice or Base R, becomes an accessible chart:

```{r setup, include = FALSE}
library(maidr)
library(ggplot2)
```

```{r cars, fig.cap = "Cars by cylinder count"}
ggplot(mtcars, aes(factor(cyl))) + geom_bar()
```
  • Charts are part of the page. In HTML output (html_document, bookdown, Quarto, reveal.js, ioslides, slidy, flexdashboard and Quarto dashboards) each chart is an <svg> in the page, not an iframe, and the page loads maidr.js once however many charts it has: from the document’s _files folder, or embedded in it when the document is self_contained or uses embed-resources. Tab moves into a chart and Shift+Tab out of it. While a chart has the focus, its keys go to the chart, not to the slide deck, book or website around it.
  • Several charts in a chunk. A chunk can return a chart, print() several in a loop, or draw several Base R charts. Each takes the place of its own figure, with that figure’s caption, alt text and number, so fig.cap, fig.alt, bookdown’s \@ref(fig:label) and Quarto’s @fig- references work as they do for images. A figure that is not one chart maidr can read, such as a grid drawing or a chart something else was drawn over, stays knitr’s image. In R Markdown and bookdown a chart’s caption is plain text: Markdown, maths and \@ref() inside fig.cap are shown as written. A bookdown text reference, fig.cap = "(ref:label)", brings them in, as Quarto does for the caption of a chart in a fig- chunk, which it writes itself.
  • Size. A chart is drawn at its chunk’s fig.width and fig.height (or fig.asp, fig.dim, R Markdown’s fig_width/fig_height and Quarto’s fig-width/fig-height), in inches, as knitr draws figures: 7 x 5 in in html_document and Quarto’s HTML, but 3 x 3 in in html_vignette, small enough that a Base R chart shows fewer tick labels unless a chunk sets a larger size. out.width still sets the width a chart is shown at, and a chart wider than the page shrinks to fit it. See Chart size for what the size changes.
  • Cache and animations. A chunk cached with cache = TRUE brings its charts back; one cached with cache = 1 or cache = 2 shows knitr’s static figures when it is rendered again from the cache. fig.show = "animate" stays knitr’s animation.
  • Static figures are SVG. In HTML output maidr records a chunk’s figures with svglite instead of knitr’s default png, so the ones that stay images are vector images too. A device a chunk names (dev = "png"), a document device other than png, and the device of a cached chunk, of an animation and of a chunk that crops its figures or uses fig.process are kept. To keep png for every chunk, set options(maidr.knitr_dev = FALSE) before rendering or in the setup chunk.
  • Other outputs. In PDF, Word, Markdown (github_document), EPUB and xaringan output, plots are knitr’s figures, as without maidr. HTML that cannot hold a chart in the page, such as an HTML fragment or pagedown, keeps each chart in an iframe of its own.
  • Return or print a chart; do not show() it. A chart a document returns or prints never opens the viewer. show() still does: in a document it opens a browser during the render and puts nothing in the page.
  • Turning it off. maidr_off() in a chunk knits the chunks after it as they would be without maidr, and maidr_on() turns maidr back on. maidr_off() lasts for the R session, not only the document: a later document rendered in the same session, such as a later vignette of R CMD build, stays off too, so a document that turns maidr off should end with maidr_on(). Documents that call maidr_on() in their setup chunk keep working; the call is no longer needed there.
  • A session with maidr loaded. Any document rendered in an R session where maidr is loaded – by library(maidr) at the console, or by loading its namespace alone, as a package that imports maidr does – gets charts and svglite figures, whether or not it loads maidr itself. options(maidr.auto_show = FALSE) before the render prevents that, and options(maidr.knitr_dev = FALSE) keeps png figures.

How maidr hooks into your session

  • Console. library(maidr) is all it takes. Printing a ggplot2 object, by typing p or print(p), opens it in the maidr viewer; show(p) is the explicit form. Base R plotting calls are recorded, and show() with no argument opens the recorded chart. save_html() writes any of them to a file.
  • lattice. Printing a lattice chart opens the viewer too, through lattice’s own print.function option, which maidr sets once lattice is loaded. A print that shares its page with other charts (split, position, more = TRUE, newpage = FALSE), a print into a file device such as pdf() or png(), and plot(p), which lattice does not route through that option, are drawn by lattice as before, and so is a chart maidr cannot read.
  • R Markdown and Quarto. library(maidr) in a setup chunk is enough. Every plot the document draws becomes an accessible chart in place of its figure, including charts printed with print(p) in a loop and several Base R charts in one chunk; see R Markdown and Quarto.
  • Shiny. Put maidr_output() in the UI and render_maidr() in the server, with its expression returning the ggplot2 or lattice chart rather than printing it; see vignette("shiny-integration", package = "maidr").
  • Turning it off. maidr_off() stops interception for the session and maidr_on() starts it again. options(maidr.ggplot2 = FALSE) leaves ggplot2 printing alone, options(maidr.lattice = FALSE) leaves lattice printing alone, options(maidr.base_r = FALSE) stops recording Base R calls, and options(maidr.auto_show = FALSE), in .Rprofile to make it permanent, turns everything off. See ?"maidr-options".
  • What gets masked. Attaching maidr puts its own copies of the Base R plotting functions, and of methods::show(), ahead of the originals; R lists them at library(maidr). Each records the call and passes through to the original, and show() hands anything that is not a plot back to methods::show(). In a script or a package call maidr::show() by name, and attach vioplot, wordcloud, quantmod or ROCR before maidr, or their own functions mask the wrappers and their charts go unrecorded – ROCR’s plot() masks maidr’s for every chart, not only its own. See ?"base-r-wrappers".

Supported plot types

maidr supports a wide range of visualization types in both ggplot2 and Base R, in the two tables below. It also reads lattice charts, but only as experimental types, so lattice has no column here: its charts are listed under Experimental Plot Types.

Basic Plot Types

Plot Type ggplot2 Base R
Bar charts geom_bar(), geom_col() barplot()
Grouped/Dodged bars position = "dodge" beside = TRUE
Stacked bars position = "stack" beside = FALSE
Pie charts geom_col()/geom_bar() + coord_polar("y") pie()
Histograms geom_histogram() hist()
Scatter plots geom_point() plot()
Line plots geom_line() plot(type = "l"), lines()
Step plots geom_step() plot(type = "s"), plot(type = "S")
Box plots geom_boxplot() boxplot()
Heatmaps geom_tile() image()
Contour plots — (geom_contour() is [experimental], see below) contour()
Violin plots geom_violin() — (vioplot::vioplot() is [experimental], see below)
Candlestick (OHLC) tidyquant::geom_candlestick() (+ geom_ma(), + patchwork volume) quantmod::chartSeries() (OHLC-only; no TA / no volume)
Density/Smooth geom_smooth(), geom_density() lines(density())

Note: Volume bars and moving-average overlays for candlestick charts are supported only on the ggplot2 + {tidyquant} + {patchwork} path. On the Base R path, quantmod::chartSeries() TA overlays (addVo(), addSMA(), addEMA()) — and the default TA whenever the input xts carries a Volume column — fall back to native (non-accessible) graphics with a one-time advisory.

Advanced Plot Types

Plot Type ggplot2 Base R
Faceted plots facet_wrap(), facet_grid() par(mfrow/mfcol) + loops
Multi-panel layouts patchwork package par(mfrow), par(mfcol)
Multi-layered plots Multiple geom_* layers Sequential plot calls

Experimental Plot Types

[!WARNING] These are prototypes. Treat them as prototypes. They are under active development, they are unstable, and none of them has been through a user study. Field names, announcement wording and navigation may change without a deprecation period, including in a patch release. If you are building something that has to keep working, build it on the plot types above.

Everything in the two tables above predates the plot coverage roadmap (#137) and has been exercised by real readers over real charts. Everything below was added by that roadmap, by the base R sweeps that followed it (#251, #262) or with the lattice reading (#333), most inside a few weeks.

Each was measured against the chart it reads — that is what the issues and the tests record. But measuring that a reading is faithful to the drawing is a different claim from establishing that it is useful to a reader. Nobody has asked a blind or low-vision reader whether hearing stars() as a radar, or navigating a termplot() panel by panel, is the right way to read one. Until that happens these are proposals about how a chart could be read, not answers.

Feedback is exactly what would move one of these into the tables above.

Elsewhere in these docs — the example articles, the getting-started vignette and the package help — an experimental type is marked [experimental] after its name; a type with no mark is stable. Wherever they list plot types, the stable ones come first and the experimental ones follow in a section of their own, as they do here.

ggplot2

Layer type Drawn by
area geom_area(), geom_ribbon(aes(ymin = 0, ...))
stacked_area stacked geom_area()
stacked_normalized_area geom_area(position = "fill")
stacked_normalized_bar geom_bar(position = "fill")
contour geom_contour(), geom_density_2d()
directed_graph ggraph::ggraph() of a directed graph (the node layer; edges are read from the graph)
error_bar geom_errorbar(), geom_errorbarh(), geom_linerange(), geom_pointrange(), geom_crossbar(), geom_ribbon() as a band other than a median_hilow summary
gantt geom_segment(), geom_curve(), maidr_gantt()
hexbin geom_hex(), stat_bin_2d()
percentile_band ggdist::stat_lineribbon(), ggdist::geom_lineribbon() of a median_qi() summary, stat_summary(geom = "ribbon", fun.data = median_hilow) (with its stat_summary() median line)
polygon geom_polygon()
pr_curve maidr_pr_curve(), autoplot() of a yardstick::pr_curve()
roc maidr_roc(), pROC::ggroc(), autoplot() of a yardstick::roc_curve()
rug geom_rug()

Base R

Layer type Drawn by
biplot biplot()
box_stats bxp()
conditional_density cdplot()
correlogram acf(), pacf(), ccf()
cumulative_periodogram cpgram()
directed_graph igraph’s plot() of a directed graph (circle vertices)
dot dotchart() (ungrouped)
filled_contour filled.contour()
fourfold fourfoldplot() (2x2 tables, std = "ind.max" / "all.max")
interaction interaction.plot()
lag lag.plot()
lollipop plot(type = "h")
mosaic mosaicplot() (two-way tables)
pairs pairs()
qq qqnorm()
qqline qqline()
radar stars()
residual assocplot() (two-way tables)
rocr_performance ROCR’s plot() of a performance object: a pr_curve layer for performance(pred, "prec", "rec"), a line for any other measure (attach ROCR before maidr)
spectral_density spectrum()
spine spineplot()
stacked_normalized_bar barplot() of proportions
strip stripchart()
subseries monthplot()
termplot termplot()
violin vioplot::vioplot()
word_cloud wordcloud::wordcloud()

lattice

Every chart maidr reads from lattice is experimental, including those read as a layer type that is stable for ggplot2 and Base R: a barchart() is emitted as the same bar layer as barplot(), but reading what lattice drew, panel by panel and group by group, is new.

Layer type Drawn by
bar barchart() without groups, histogram() of a factor with one bar per level
dodged_bar barchart() with groups
stacked_bar barchart() with groups and stack = TRUE, barchart() of a table or matrix
hist histogram()
point xyplot(), stripplot(), qqmath(), qq(), dotplot() with several values on a level
line xyplot(type = "l") and the lines of "b", "o" and "a", xyplot() of a time series, and the same types on stripplot(), dotplot(), qqmath() and qq()
step xyplot(type = "s"), xyplot(type = "S")
box bwplot()
heat levelplot(), contourplot(region = TRUE)
contour contourplot(), levelplot(contour = TRUE)
smooth densityplot(), and xyplot(), qqmath() and qq() with type = "r", "smooth" or "spline" on numeric axes
dot dotplot() with one value per level
lollipop xyplot(type = "h"), and type = "h" on stripplot(), dotplot(), qqmath() and qq()

A conditioned chart (y ~ x | g) is read one panel at a time, each panel a subplot, laid out as lattice lays them out; groups gives one point layer per group, or one series per group on a line or curve – one layer per group when the groups’ curves share no x value, since Up and Down only move between series that meet at the x being read. A chart laid out over several pages is read from its first page, with a warning. What the reading does not cover is shown as a static image: cloud(), wireframe(), splom(), parallelplot(), a panel function of your own or one such as panel.violin, levelplot(useRaster = TRUE), latticeExtra layers and compositions, a fit (type = "r", "smooth" or "spline") over a factor axis, as on a stripplot() or dotplot(), and a panel that fails to draw.

The split is the diff of each factory’s get_supported_types() against 8de0e98, the last commit on main before #137 was filed. The lattice factory came later, so every type it reads is experimental. tests/testthat/test-plot-type-stability.R checks all three factories — ggplot2, Base R and lattice — and fails if a type one of them supports appears in neither the stable tables nor its experimental table, so a new layer type has to be placed deliberately rather than inherit either promise by being forgotten.

The JavaScript core and the Python binding make the same distinction over their own type lists, with the same boundary and for the same reason, and mark their docs the same way: see the JavaScript core’s trace type stability and the Python binding’s stability page.

See the examples gallery for a worked example of each plot type.

Accessibility features

  • Keyboard navigation - explore data points using arrow keys
  • Screen reader support - full ARIA labels and live announcements
  • Sonification - hear data patterns through sound
  • Text descriptions - automatic statistical summaries

The keys a reader needs first, the same on every page of this documentation:

Key Action
Tab Focus the chart; Shift + Tab leaves it
Left / Right Move between data points
Up / Down Move between series, stacked segments, heat map rows or box plot sections, on a chart that has them
Page Up / Page Down Switch between the layers of a chart that has several
B Toggle braille mode
T Toggle text mode
S Toggle sonification
R Toggle review mode
C Toggle high contrast mode
L, then X, Y or T Announce the x axis label, the y axis label or the title
Space Repeat the current sound
Ctrl + / (Cmd + / on macOS) Show or hide the full keyboard shortcut help

Every other shortcut, including autoplay, jumping to the ends, the command palette, settings and the AI chat, is on the MAIDR controls reference.

Offline support

By default, show() and save_html() use the bundled maidr.js library, so the result works offline. save_html() writes the library to a lib/ folder beside the file, and the two have to be shared together: zip the folder that holds both, or copy both. An .html sent on its own loads no maidr.js and shows a plain, inaccessible chart. A knitted R Markdown or Quarto page loads the bundled maidr.js once for all its charts, from its _files folder or embedded in it when it is self_contained / uses embed-resources, so it works offline wherever it was rendered. Widgets, Shiny apps, and the few knitted outputs that keep a chart in an iframe (an HTML fragment, pagedown) auto-detect internet availability and use the CDN when online. A page holding a widget rendered online also carries its own copy of maidr.js, which its charts fall back on when the CDN cannot be reached, so a self_contained / embed-resources page works offline too. Use the use_cdn parameter for explicit control:

# Force CDN: one self-contained file, needs internet whenever it is viewed
show(p, use_cdn = TRUE)
save_html(p, "plot.html", use_cdn = TRUE)

# Force bundled files: works offline, lib/ folder beside the saved file
show(p, use_cdn = FALSE)
save_html(p, "plot.html", use_cdn = FALSE)

The CDN paths load the latest published maidr.js, not the copy bundled with this package, as the Python binding does. The first CDN document in an R session asks jsDelivr (then the npm registry) which version that is, within 3 seconds, and every document in the session names that version. If the lookup cannot be made it costs no error: the document names the bundled version instead, the copy use_cdn = FALSE would serve. Pin a version when a document has to load the same maidr.js whenever it is opened:

options(maidr.cdn_version = "bundled")  # the bundled version, no lookup
options(maidr.cdn_version = "4.9.0")    # a particular release

or set MAIDR_CDN_VERSION in the environment. use_cdn = FALSE never makes that lookup. See ?"maidr-options".

Two things still reach the network from an offline document, and only when a reader uses them. One is a language other than English. maidr.js reads charts in English on its own and fetches Korean, Japanese, Chinese, Spanish, German, French, Italian or Hindi as a small pack from beside itself. This package does not bundle the packs, which would add 0.8 MB against CRAN’s size limit, so a use_cdn = FALSE document points maidr.js at the packs of the bundled version on jsDelivr: a reader whose language is not English hears it when online, and English when not. Serve the packs yourself, or turn this off:

options(maidr.locale_base_url = "https://example.org/maidr/")  # your own copy
options(maidr.locale_base_url = FALSE)  # never fetch a pack: English only

The other is connecting a DotPad tactile display. maidr.js does not bundle the DotPad SDK, whose braille engine is a 14 MB liblouis build, and imports the vendor’s copy from jsDelivr the first time a DotPad is connected. Rendering, sonification and braille work offline regardless. To keep the DotPad offline too, download the pinned SDK once and every use_cdn = FALSE document carries it in its lib/ folder:

maidr_download_dotpad_sdk()          # ~14 MB, once, into a per-user cache
save_html(p, "plot.html", use_cdn = FALSE)   # lib/dotpad-sdk-<version>/ beside it

A page served from elsewhere, or a knitted R Markdown or Quarto document, which does not carry the downloaded copy, names its copy by URL instead, through options or the environment variables of the same names:

options(
  maidr.dotpad_sdk_url = "https://intranet.example/dotpad/DotPadSDK-3.0.3.js",
  maidr.dotpad_asset_base_url = "https://intranet.example/dotpad/lib/"
)
# or: Sys.setenv(MAIDR_DOTPAD_SDK_URL = "...", MAIDR_DOTPAD_ASSET_BASE_URL = "...")

Every document maidr produces then declares window.MAIDR_DOTPAD_SDK_URL and window.MAIDR_DOTPAD_ASSET_BASE_URL ahead of maidr.js. See ?"maidr-options".

Getting help

Learning more

maidr for R is one of three MAIDR packages, all developed by the (x)Ability Design Lab at the University of Illinois Urbana-Champaign:

  • MAIDR JavaScript core, the TypeScript engine (npm package maidr) that renders every accessible chart, including the ones this package produces.
  • py-maidr for Python, the Python binding for matplotlib, seaborn, Plotly and Altair (PyPI package maidr).
  • maidr for R, this package, for ggplot2 and Base R graphics, with experimental lattice support (CRAN package maidr; source at xability/r-maidr).

Citation

If you use maidr in research, please cite the MAIDR papers:

  • Seo, J., Xia, Y., Lee, B., Mccurry, S., & Yam, Y. J. (2024). MAIDR: Making Statistical Visualizations Accessible with Multimodal Data Representation. In Proceedings of the CHI Conference on Human Factors in Computing Systems (CHI ’24). ACM. https://doi.org/10.1145/3613904.3642730
  • Seo, J., O’Modhrain, S., Xia, Y., Kamath, S., Lee, B., & Coughlan, J. M. (2024). Designing Born-Accessible Courses in Data Science and Visualization: Challenges and Opportunities of a Remote Curriculum Taught by Blind Instructors to Blind Students. In EuroVis 2024 - Education Papers. The Eurographics Association. https://doi.org/10.2312/eved.20241053

citation("maidr") prints both, plus an entry for the package itself, in text and BibTeX form.