Configure Accessibility tests

You can configure Chromatic’s accessibility tests to match your project’s specific requirements. By default, Chromatic runs accessibility tests with the following rules:

• WCAG 2.0 Level A & AA Rules
• WCAG 2.1 Level A & AA Rules
• Best Practices Rules

The region rule is disabled because you’re testing individual stories, not entire pages, so the story will likely lack the HTML5 landmark element.

How do I configure the Accessibility addon?

All configuration—such as selecting which rules to evaluate the UI against or enabling/disabling specific axe features—is managed through Storybook.

The Accessibility addon is configured via the a11y parameter which accepts the following properties:

• element (optional): the selector to inspect. Defaults to body.
• config: Options passed to axe.configure. See axe.configure API docs to learn more about the available options.
• options: axe’s options parameter. See options parameter API docs to learn more about the available options.

Here’s an example configuration for the Accessibility addon in Storybook:

// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite)
// if you're using Storybook 9, or with the appropriate renderer otherwise.
import { Preview } from "@storybook/your-framework";

const preview: Preview = {
  parameters: {
    a11y: {
      // Optional selector to inspect
      element: "body",
      /*
       * Options passed to axe.configure
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#api-name-axeconfigure
       * to learn more about the available options.
       */
      config: {
        rules: [
          {
            // The autocomplete rule will not run based on the CSS selector provided
            id: "autocomplete-valid",
            selector: '*:not([autocomplete="nope"])',
          },
          {
            // Setting the enabled option to false will disable checks for this particular rule on all stories.
            id: "image-alt",
            enabled: false,
          },
        ],
      },
      /*
       * axe's options parameter
       * See https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#options-parameter
       * to learn more about the available options.
       */
      options: {},
    },
  },
  globals: {
    a11y: {
      // Optional flag to prevent the automatic check within Storybook
      manual: true,
    },
  },
};

export default preview;

For more on configuring the Accessibility addon, refer to the Storybook docs.

Run all rules for a specific compliance standard

You can use tags to run rules specific to a standard, such as WCAG 2.2 Level AA, EN-301-549 (European Accessibility Act), etc. For example:

// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite)
// if you're using Storybook 9, or with the appropriate renderer otherwise.
import { Preview } from "@storybook/your-framework";

const preview: Preview = {
  parameters: {
    a11y: {
      configure: {},
      options: {
        runOnly: {
          type: "tag",
          // eg: If you wanted to specifically meet the standards of European Accessibility Act
          // Full list of available tags: https://github.com/dequelabs/axe-core/blob/develop/doc/API.md#axe-core-tags
          values: ["EN-301-549"],
        },
      },
    },
  },
};

export default preview;

Disable accessibility tests

Both in Storybook and Chromatic

For Storybook 8+, use the a11y global to disable accessibility tests for a story and/or component, both in Storybook and Chromatic.

// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from "@storybook/your-framework";
import { MyComponent } from "./MyComponent";

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const NonA11yStory: Story = {
  globals: {
    a11y: {
      // This option disables all automatic a11y checks on this story
      manual: true,
    },
  },
} satisfies Story;

Only in Chromatic

To disable Accessibility Tests only within Chromatic you can use the chromatic.disableSnapshot parameter. Note, this will also disable visual tests for this story and/or component.

// Adjust this import to match your framework (e.g., nextjs, vue3-vite)
import type { Meta, StoryObj } from "@storybook/your-framework";
import { MyComponent } from "./MyComponent";

const meta: Meta<typeof MyComponent> = {
  component: MyComponent,
  title: "MyComponent",
  parameters: {
    // Disables Chromatic tests on a component level
    chromatic: { disableSnapshot: true },
  },
};

export default meta;
type Story = StoryObj<typeof MyComponent>;

export const Default: Story = {};