MAIDR Logo

MAIDR: Multimodal Access and Interactive Data Representation

MAIDR (Multimodal Access and Interactive Data Representation, pronounced "mader") is an open-source JavaScript/TypeScript library that makes statistical charts accessible to blind and low-vision people. It adds keyboard navigation, sonification, text descriptions, braille output and AI-generated descriptions to charts drawn with React, Recharts, Plotly, Vega-Lite, D3, Chart.js, Apache ECharts, Highcharts and other libraries, or described directly with its JSON data schema. MAIDR is developed by the (x)Ability Design Lab at the University of Illinois Urbana-Champaign and is the engine behind py-maidr for Python and maidr for R.

maidr is the npm package that ships MAIDR. It aims to provide an inclusive experience for users with visual impairments by offering multiple modes of interaction: braille, text, and sonification (BTS). This comprehensive approach enhances the accessibility of data visualization and encourages a multi-modal exploration on visualization.

Table of Contents

  1. Usage
  2. Data Schema
  3. React Integration
  4. Controls
  5. Live & Streaming Data
  6. Braille Generation
  7. Languages
  8. Examples
  9. Related projects
  10. Papers
  11. License
  12. Contact
  13. Acknowledgments

Usage

To use maidr, follow these steps:

  1. Import your plot: maidr is designed to work seamlessly with scalable vector graphics (SVG) objects for visual highlighting. However, maidr is inherently visual-agnostic, and it also supports other raster image formats such as PNG and JPG without the visual highlight feature. Regardless of the image format, maidr provides support for all non-visual modalities, including Braille, text, and sonification (BTS). Additionally, it offers interactive and artificial intelligence (AI) plot descriptions powered by OpenAI GPT, Anthropic Claude, Google Gemini, or local models running on your own machine via Ollama (no API key required, suitable for sensitive data). The supported plot types include bar plot, boxplot, heatmap, scatter plot, line plot, step plot, histogram, pie chart, segmented bar plots (e.g., stacked bar plot, side-by-side dodged plot, and normalized stacked bar plot).

  2. Create an HTML file: Include the main script file maidr.js. No stylesheet link is needed — maidr styles its own interface at runtime, and fetches the stylesheet for mathematical notation on demand when it is actually required. Add the SVG of your plot to the main HTML body, and add an ID attribute of your choice to the SVG. Note that this can be automated with R. Your HTML file should now have the following structure:

    <!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>maidr Example</title>
    <script src="https://cdn.jsdelivr.net/npm/maidr@latest/dist/maidr.js"></script>
  </head>
  <body>
    <div>
      <!-- Your SVG plot is here -->
    </div>
  </body>
</html>

    maidr is also served by cdnjs, which matters when a page cannot reach jsDelivr: sandboxed embedding contexts allow a fixed set of CDN hosts, and a page whose script-src names cdnjs.cloudflare.com cannot load maidr from jsDelivr however well jsDelivr works everywhere else.

    <script src="https://cdnjs.cloudflare.com/ajax/libs/maidr/3.75.1/maidr.min.js"></script>

    That URL names a version, because cdnjs serves no floating alias: it stays on 3.75.1 until someone changes it, and the library page lists the current release.

    maidr.js is the only script mirrored on cdnjs, which decides how much of a guide below cdnjs can serve. The Plotly guide needs nothing else from maidr — Plotly charts are detected without help — so swapping in the URL above covers its whole maidr side. Every other guide also loads a per-chart-library adapter bundle (d3.js, anychart.mjs, chartjs.js, highcharts.js and so on) to bind the chart, and those are not mirrored, so they load from jsDelivr. Where the charting library itself comes from is a third question, which each guide answers for itself.

  3. Add your data: Define the maidr JSON schema for your plot. See the Data Schema documentation for the full schema structure, object properties, and data formats for each plot type.

Data Schema

The maidr JSON schema defines how plot data is structured for each supported plot type, including bar plots, boxplots, heatmaps, scatter plots, line plots, step plots, histograms, pie charts, and segmented bar plots. For the full schema structure, object properties, and data formats, see the Data Schema documentation.

React Integration

MAIDR provides a React component for use in React applications. Install via npm:

npm install maidr

Then import and use the <Maidr> component:

import { Maidr } from 'maidr/react';
import type { MaidrData } from 'maidr/react';

const chartData: MaidrData = {
  id: 'my-chart',
  title: 'Sales by Quarter',
  subplots: [[{
    layers: [{
      id: '0',
      type: 'bar',
      axes: { x: 'Quarter', y: 'Revenue' },
      data: [
        { x: 'Q1', y: 120 },
        { x: 'Q2', y: 200 },
        { x: 'Q3', y: 150 },
        { x: 'Q4', y: 280 },
      ],
    }],
  }]],
};

function App() {
  return (
    <Maidr data={chartData}>
      <svg>{/* Your chart SVG */}</svg>
    </Maidr>
  );
}

Each <Maidr> instance is fully isolated — you can render multiple accessible charts on the same page. Requires React 18 or 19.

For the full React guide with TypeScript types reference, data examples for all plot types, and advanced usage, see the React documentation.

Controls

maidr provides keyboard-based interaction for navigating and exploring plots. Press Tab (or click) to focus a plot, move through data points with the arrow keys, and toggle B braille, T text, S sonification, and R review mode. Four global shortcuts open maidr's own interfaces:

Action Windows / Linux macOS
Show or hide the keyboard shortcut help Ctrl + / Command + /
Open the command palette listing every available command Ctrl + Shift + P Command + Shift + P
Open the AI chat (requires your own API key, entered in Settings, or a local Ollama server) Shift + / (that is, ?) Shift + / (?)
Open Settings Ctrl + , Command + ,

For the complete list of keyboard shortcuts and interaction controls, see the Controls documentation.

Live & Streaming Data

maidr supports realtime data updates for live-updating visualizations (stock tickers, sensor dashboards, live metrics). Charts configured with live: true can be updated in place via window.maidrLive.setData() / appendData() (script tag) or by updating the data prop (React), with an optional maxWidth sliding window for streaming. Pressing M toggles monitor mode, which auto-sonifies and announces newly appended data points. For the full API and examples, see the Live & Streaming Data documentation.

Braille Generation

MAIDR incorporates a Braille mode that represents plots using Braille symbols, allowing users to explore data using a refreshable Braille display. Different plot types use unique encoding strategies tailored to convey data distribution, patterns, and trends. For detailed encoding schemes for each plot type, see the Braille Generation documentation.

Languages

Every announcement and dialog can be read in English, 한국어, 日本語, 中文, Español, Deutsch, Français, Italiano, or हिन्दी. Choose the language on the General tab of Settings; by default MAIDR follows the browser's language. English is built in and each other language is a small locale pack beside maidr.js that MAIDR fetches when needed (or import 'maidr/locale/ko'). Chart data is read as the author wrote it; only MAIDR's own words are translated. For how the dictionaries work and how to add a language, see the Languages documentation.

Examples

Example plots are demonstrated here.

For more information, refer to the example HTML files provided in the directory examples/

MAIDR is one of three sibling projects from the (x)Ability Design Lab. This repository is the JavaScript core; the two language bindings render their plots with it.

Papers

To learn more about the theoretical background and user study results, we recommend you read and cite the following papers.

  1. MAIDR: Making Statistical Visualizations Accessible with Multimodal Data Representation:

    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

@inproceedings{seoMAIDRMakingStatistical2024,
  title      = {{{MAIDR}}: {{Making Statistical Visualizations Accessible}} with {{Multimodal Data Representation}}},
  shorttitle = {{{MAIDR}}},
  booktitle  = {Proceedings of the {{CHI Conference}} on {{Human Factors}} in {{Computing Systems}}},
  author     = {Seo, JooYoung and Xia, Yilin and Lee, Bongshin and Mccurry, Sean and Yam, Yu Jun},
  year       = {2024},
  month      = may,
  series     = {{{CHI}} '24},
  pages      = {1--22},
  publisher  = {Association for Computing Machinery},
  address    = {New York, NY, USA},
  doi        = {10.1145/3613904.3642730},
  urldate    = {2024-05-14},
  abstract   = {This paper investigates new data exploration experiences that enable blind users to interact with statistical data visualizations---bar plots, heat maps, box plots, and scatter plots---leveraging multimodal data representations. In addition to sonification and textual descriptions that are commonly employed by existing accessible visualizations, our MAIDR (multimodal access and interactive data representation) system incorporates two additional modalities (braille and review) that offer complementary benefits. It also provides blind users with the autonomy and control to interactively access and understand data visualizations. In a user study involving 11 blind participants, we found the MAIDR system facilitated the accurate interpretation of statistical visualizations. Participants exhibited a range of strategies in combining multiple modalities, influenced by their past interactions and experiences with data visualizations. This work accentuates the overlooked potential of combining refreshable tactile representation with other modalities and elevates the discussion on the importance of user autonomy when designing accessible data visualizations.},
  isbn       = {9798400703300},
  keywords   = {Accessibility,Blind,Braille Display,Multimodality,Screen Readers,Statistical Visualization}
}

  1. Designing Born-Accessible Courses in Data Science and Visualization: Challenges and Opportunities of a Remote Curriculum Taught by Blind Instructors to Blind Students:

    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

@inproceedings{10.2312:eved.20241053,
  booktitle = {EuroVis 2024 - Education Papers},
  editor    = {Firat, Elif E. and Laramee, Robert S. and Andersen, Nicklas Sindelv},
  title     = {{Designing Born-Accessible Courses in Data Science and Visualization: Challenges and Opportunities of a Remote Curriculum Taught by Blind Instructors
               to Blind Students}},
  author    = {JooYoung Seo and Sile O'Modhrain and Yilin Xia and Sanchita Kamath and Bongshin Lee and James M. Coughlan},
  year      = {2024},
  publisher = {The Eurographics Association},
  isbn      = {978-3-03868-257-8},
  doi       = {10.2312/eved.20241053}
}

License

This project is licensed under the GNU General Public License v3.0 or later (GPL-3.0-or-later). See the LICENSE file for the full license text.

Contact

For any inquiries or suggestions, please contact the principal investigator:

JooYoung Seo - jseo1005@illinois.edu

Acknowledgments

This project is conducted through the (x)Ability Design Lab at the University of Illinois at Urbana-Champaign, and funded by multiple grants, including: