API

Exports#

• accented. The function that enables the continuous scanning and highlighting of accessibility issues on the page. Example: const disable = accented(options);
  • Parameters: the only parameter (optional) is options. See Options.
  • Returns: a disable function (no parameters). When called, it stops scanning and highlighting and cleans up any changes made to the page.

Type exports#

The following types are exported for TypeScript consumers:

• AccentedOptions: the options parameter (see Options).
• DisableAccented: the type of the function returned by accented.

Options#

axeOptions#

Type: object.

Default: {}.

The options parameter for axe.run().

Accented supports only two keys of the original options object:

• rules;
• runOnly.

Both are optional and control which accessibility rules Accented tests against.

See axe-core options documentation.

callback#

Type: function.

Default: no-op (() => {}).

A function that will be called after each scan.

Potential uses include sending results to a backend or measuring performance.

It accepts a single params object with the following properties:

• elementsWithIssues: the most up-to-date array of all elements with accessibility issues.
• performance: performance metrics from the last scan. Includes:
  • totalBlockingTime: how long the main thread was blocked by Accented during the last scan, in milliseconds. It’s further divided into the scan and domUpdate phases.
  • scan: how long scanning (the execution of axe.run()) took, in milliseconds.
  • domUpdate: how long the DOM update (adding / removing outlines and dialog trigger buttons) took, in milliseconds.
• scanContext: nodes that got scanned. Either an array of nodes, or an object with include and exclude properties (if any nodes were excluded).

Example:

accented({
  callback: ({ elementsWithIssues, performance, scanContext }) => {
    console.log('Elements with issues:', elementsWithIssues);
    console.log('Total blocking time:', performance.totalBlockingTime);
    console.log('Scan context:', scanContext);
  },
});

context#

Type: see details below.

Default: document.

The context parameter for axe.run().

Determines what part(s) of the page to scan for accessibility issues.

Accepts a variety of shapes:

• a Node (in practice it will likely be an instance of Element, Document, or DocumentFragment);
• a valid CSS selector;
• an object for selecting elements within shadow DOM, whose shape is { fromShadowDom: [selector1, selector2, ...] }, where selector1, selector2, etc. select shadow hosts, and the last selector selects the actual context. In this example, selector2 targets an element within the shadow root created on element(s) matched by selector1, so in practice you shouldn’t have more than two elements in such an array unless you have a very complex structure with multiple shadow DOM layers;
• a NodeList (likely a result of a querySelectorAll() call);
• an array containing any combination of selectors, nodes, or shadow DOM objects (described above);
• an object containing include and / or exclude properties. It’s useful if you’d like to exclude certain elements or parts of the page. The values for include and exclude can take any of the above shapes. Complex include / exclude rules are rarely needed, but if you do need them, the exact behavior is documented by the relevant tests: is-node-in-scan-context.test.ts.

See also the documentation for the context parameter of axe.run(), which the context option from Accented mostly mirrors (note that Accented doesn’t support the fromFrames object shape).

name#

Type: string.

Default: 'accented'.

The character sequence that’s used in various elements, attributes and stylesheets that Accented adds to the page.

You likely don’t need to set this unless your page already uses “accented” in element names or attributes, which could cause conflicts.

• The data attribute that’s added to elements with issues (default: data-accented).
• The names of custom elements for the button and the dialog that get created for each element with issues (default: accented-trigger, accented-dialog).
• The CSS cascade layer containing page-wide Accented-specific styles (default: accented).
• The prefix for some of the CSS custom properties used by Accented (default: --accented-).
• The window property that’s used to prevent multiple axe-core scans from running simultaneously (default: __accented_axe_running__).

Only lowercase alphanumeric characters and dashes (-) are allowed in the name, and it must start with a lowercase letter.

Example:

accented({
  name: 'my-name',
});

With the above option provided, the attribute set on elements with issues will be data-my-name, a custom element will be called my-name-trigger, and so on.

output#

By default, scan results are presented in two ways:

• as interactive highlights on the page;
• as console messages.

You can use the output option if you’d like to only keep one or the other.

For example, you may only keep the console messages if you don’t want Accented to modify the DOM of your app (see Console-only mode).

Or, may be fine with the highlights on the page, but prefer not to clutter the console.

output.console#

Type: boolean.

Default: true.

Whether the list of elements with issues should be printed to the browser console whenever issues are added, removed, or changed.

Example:

accented({
  output: {
    console: false
  }
});

In the example, the issues will not be logged to the console, while elements on the page will still be highlighted.

output.page#

Added in: v1.1.0.

Type: boolean.

Default: true.

Whether Accented should highlight elements with issues on the page.

Example:

accented({
  output: {
    page: false
  }
});

In the example, the issues will only be logged to the console, with no highlights on the page.

throttle#

An object controlling at what moments Accented will run its scans.

Learn more about throttling in Accented.

throttle.wait#

Type: number.

Default: 1000.

How long (in ms) Accented waits to run a scan after a mutation or after the previous scan finishes — whichever is later.

If the page you’re scanning has a lot of nodes, scanning may take a noticeable time (~ a few hundred milliseconds), during which time the main thread will be blocked most of the time.

You may want to experiment with this value if your page contents change frequently or if it has JavaScript-based animations running on the main thread.

throttle.leading#

Type: boolean.

Default: true.

If leading is set to true, the scan runs immediately after a mutation. In this case, wait only applies to subsequent scans, giving the page at least wait milliseconds between the end of the previous scan and the beginning of the next one.

If false, Accented waits before the first scan too — useful if you expect batches of rapid mutations.

Styling#

You can control what some aspects of Accented UI look like by setting the following props in your application (see Styling in Getting started for a discussion of when you might need this):

• --accented-primary-color. Color of outlines and trigger button background. Default: violet-red (oklch(0.5 0.3 0)).
• --accented-secondary-color. Trigger button text color. Default: white (oklch(0.98 0 0)).
• --accented-outline-width. Default: 2px.
• --accented-outline-style. Default: solid.

Note: Accented’s default values are defined within @layer accented, so if you use the default layer to define your custom properties, they’re guaranteed to take precedence over the default ones. Learn more about CSS layers.

Note: when you set the name option, the custom property names and CSS layer will follow that value.

For example, if name: 'my-name', then the CSS custom properties will be --my-name-primary-color, --my-name-secondary-color, and so on, and those will be defined within @layer my-name.