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, 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

Controls how scan results are presented.

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.

throttle

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

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.