Examples

axe-tools is built as both an ES module and a Universal module (umd). As a result it is able to integrate with all web applications. It has special support for Vue apps through a plugin, but it will also examine the DOM on any page. You can import the library through an import statement or a <script> tag. Review the examples below to get started.

HTML

<script src="https://tools.ais.its.uiowa.edu/axe-tools/axe-tools.umd.js"></script>
<script>
    //console.log('AXE TOOLS CONFIG', axeTools)
    
    axeTools.setPageRoute('${play.mvc.Router.route(request).path}')
    //console.log('Page Route', axeTools.getPageRoute())
    
    axeTools.registerAxeReporter({
        appName: 'Campus Data',
        teamName: 'Ent-Apps',
        logReport: true,
        timeout: 5000
    })
</script>

For applications that use a traditional request/response page model, the library can be imported with a <script> tag. This example pulls the latest version of the library. Developers can also pin usage to a specific version by using the path /versions/axe-tools/{x.y.z}/axe-tools.umd.js. The library's API is exposed through the global variable axeTools. Typically, these scripts are imported on an application's site template(s) although they can be added on a page-by-page basis as needed.

The first call to setPageRoute() is optional. It communicates the parameterized route to Axe Tools. This example is from a Play application, and we use the Play router to access the parameterized route.

The second call, registerAxeReporter() does all the heavy lifting to configure axe-tools. It will create all the necessary event listeners to scan the page after the specified timeout and after any DOM changes. See the options for details on configuration.

Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

Vue 3

// main.ts
import {AxeToolsPlugin, resolveEnvironment} from '@ais-public/axe-tools'
// ...

const app = createApp(App)
//...

app.use(AxeToolsPlugin, {
  appName: 'axe-tools-example',
  teamName: 'ent-apps',
  logReport: true,
  baseUrl: 'http://localhost:5173',
  env: resolveEnvironment(),
  router: router
})

app.mount('#app')

Axe Tools supports Vue applications by exposing the plugin AxeToolsPlugin. It is installed using Vue's standard use() method.

Note the execution environment is determined with a call to resolveEnvironment(). Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

Finally, we provide the Vue router to the plugin. This allows the plugin to automatically use parameterized route paths to collect related errors in a single bucket.

Nuxt 3

// {nuxt-root}/plugins/axe-tools.client.ts
import {AxeToolsPlugin, resolveEnvironment} from "@ais-public/axe-tools"
import type {AxeToolsOptions, Env} from "@ais-public/axe-tools"
import {useRouter} from "#imports";

export default defineNuxtPlugin((nuxtApp) => {

  const router = useRouter()
  let env: Env = resolveEnvironment("profiles.uiowa.edu");

  nuxtApp.vueApp.use(AxeToolsPlugin, {
    appName: 'Profiles',
    teamName: 'Ent-Apps',
    logReport: env !== 'PROD',
    baseUrl: origin,
    timeout: 5000,
    router: router,
    env: env
  } as AxeToolsOptions)
})

AxeToolsPlugin can be used in a Nuxt application by creating a client-only Nuxt plugin. Create a file axe-tools.client.ts in your /plugins directory. You can access the Vue application via the nuxtApp object. Nuxt will automatically load the plugin on startup.

Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

Vue 2

// App.vue
<script>
import {AxeReporter, resolveEnvironment } from '@ais-public/axe-tools';
import router from "./router";

export default {
  
  data: () => ({
    axeReporter: null,
    timeout: 5000,
    timeoutID: 0,
    isProdLaunch: false,
  }),
  
  created() {

      this.axeReporter = new AxeReporter(
        'elements-of-success', 
        'ESS', 
        true, 
        'https://test.its.uiowa.edu/elements-of-success',
        resolveEnvironment()
      );

      document.addEventListener('visibilitychange', () => {
        if (document.hidden) {
          const transmitSuccess = this.axeReporter.transmitMinimumResults();
          if (!transmitSuccess) {
            console.error('There was a problem transmitting accessibility telemetry');
          }
        }
      });
  },

  mounted() {
    // gets the most specific route path matched by the current route
    const currentRoutePath = router.currentRoute.matched.length > 0 ? router.currentRoute.matched[router.currentRoute.matched.length - 1].path : undefined;

    window.clearTimeout(this.timeoutID);
    this.timeoutID = window.setTimeout(() => this.axeReporter.scan(currentRoutePath), this.timeout);
  }
}
</script>

With a Vue 2 application, configuration is more manual. Developers can create the AxeReporter object in the application component (typically App.vue) on the created() event. The axe scan will be scheduled on the mounted() event.

Make sure to review the baseUrl example if your application is not deployed at the root of your domain.

baseUrl

If the host application is not running at the root of its domain, you will need to set axe-tools' baseUrl attribute to correctly collect results in the backend. That is your application is deployed at a url like apps.its.uiowa.edu/dispatch instead of events.uiowa.edu. You can dynamically compute the baseUrl using the site's origin plus base path, or you could provide a manual mapping based on all your deployment environments. Here is how NPP computes its baseUrl.

export default defineNuxtPlugin((nuxtApp) => {
  let env: Env = resolveEnvironment("apps.ais.its.uiowa.edu/npp");
  const router = useRouter();

  // Origin will evaluate to:
  // - localhost:3000
  // - test.ais.its.uiowa.edu
  // - apps.ais.its.uiowa.edu
  const origin = typeof window !== 'undefined' ? window.location.origin : '';
  
  // Will resolve to something like:
  // - apps.ais.its.uiowa.edu/npp
  const baseUrl = origin + '/npp';

  nuxtApp.vueApp.use(AxeToolsPlugin, {
    appName: 'NPP',
    teamName: 'Ent-Apps',
    baseUrl: baseUrl,
    router: router,
    env: env,
    logReport: env !== 'PROD'
  } as AxeToolsOptions);
});

Browser Extension Filtering

Browser extensions can inject content into web pages that may cause accessibility violations. Since these violations are outside of your application's control, you may want to exclude them from your accessibility reports. The filterExtensionViolations option filters out violations caused by browser extensions.

When to Use

Enable this option when:

• Users report violations that are caused by browser extensions (e.g., Grammarly, password managers, ad blockers)
• You want to focus only on violations within your application's code
• You notice violations with URLs like chrome-extension://, moz-extension://, or extension://

HTML Example

<script src="https://tools.ais.its.uiowa.edu/axe-tools/axe-tools.umd.js"></script>
<script>
    axeTools.registerAxeReporter({
        appName: 'Campus Data',
        teamName: 'Ent-Apps',
        logReport: true,
        filterExtensionViolations: true
    })
</script>

Vue 3 Example

app.use(AxeToolsPlugin, {
  appName: 'axe-tools-example',
  teamName: 'ent-apps',
  logReport: true,
  baseUrl: 'http://localhost:5173',
  env: resolveEnvironment(),
  router: router,
  filterExtensionViolations: true
})

Nuxt 3 Example

nuxtApp.vueApp.use(AxeToolsPlugin, {
  appName: 'NPP',
  teamName: 'Ent-Apps',
  baseUrl: baseUrl,
  router: router,
  env: env,
  logReport: env !== 'PROD',
  filterExtensionViolations: true
} as AxeToolsOptions);

How It Works

When filterExtensionViolations is set to true, Axe Tools will:

1. Identify violations where the HTML contains browser extension URLs
2. Filter out these violations before they are reported
3. Log the number of filtered violations to the console (when logReport is enabled)

Note: This option defaults to false to maintain backward compatibility with existing implementations.