@tw-plugins/extend-aria v0.1.0

Tailwind CSS Extend ARIA Plugin

A Tailwind CSS plugin that extends support for WAI-ARIA 1.2 attributes, providing utility variants for boolean and enumerated ARIA states to enhance accessibility styling.

Installation:

Install the plugin:

npm install --save-dev @tw-plugins/extend-aria

Usage:

Add the plugin to your Tailwind CSS configuration:

// tailwind.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [],
  theme: {},
  plugins: [require("@tw-plugins/extend-aria")],
};

or with options:

// tailwind.config.ts

import type { Config } from "tailwindcss";
import extendAria from "@tw-plugins/extend-aria";

const tailwindConfig: Config = {
  content: [],
  theme: {},
  plugins: [
    extendAria({
      // ExtendAriaPluginOptions
    }),
  ],
};

export default tailwindConfig;

Configuration Options:

attributes

A list of extendable WAI-ARIA 1.2 attributes to include in the plugin. Only attributes with boolean or enumerated values are used and accepted.

Attributes with custom or free-form values, such as aria-label, are not included. Users can still extend these manually using Tailwind's arbitrary value feature aria-[].

If not provided, the plugin defaults to including all relevant attributes except deprecated ones (if includeDeprecated is false).

Example:

const extendAria = require("@tw-plugins/extend-aria");

const tailwindConfig = {
  plugins: [
    extendAria({
      attributes: ["aria-checked", "aria-current", "aria-invalid"],
    }),
  ],
};

includeDeprecated

A flag indicating whether to include deprecated ARIA attributes.

Default is false and deprecated attributes like aria-grabbed and aria-dropeffect are excluded from the variants. To include these, explicitly set this option to true.

negate

Specifies how boolean ARIA attributes with "false" values should be handled.

Examples

Default configuration:

// tailwind.config.js

module.exports = {
  plugins: [require("@tw-plugins/extend-aria")],
};

This will include all relevant WAI-ARIA 1.2 boolean and enumerated attributes, excluding deprecated ones, and only extend "false" values where meaningful.

Include deprecated attributes:

// tailwind.config.js

const extendAria = require("@tw-plugins/extend-aria");

module.exports = {
  plugins: [extendAria({ includeDeprecated: true })],
};

Include all boolean negations:

// tailwind.config.js

const extendAria = require("@tw-plugins/extend-aria");

module.exports = {
  plugins: [extendAria({ negate: "all" })],
};

Specific boolean attributes with "false" values:

// tailwind.config.js

const extendAria = require("@tw-plugins/extend-aria");

module.exports = {
  plugins: [extendAria({ negate: ["aria-checked", "aria-pressed"] })],
};

Supported Attributes:

This plugin only supports extendable WAI-ARIA 1.2 attributes that have boolean or enumerated values. Attributes with custom values, such as aria-label, are not included. However, you can still use these with Tailwind CSS's arbitrary value feature.

Here is a list of supported attributes:

All attributes produces variants for styling based on parent and sibling states, e.g. group-aria-expanded:{utility}, peer-aria-invalid-spelling:{utility}, etc.

Contributing:

Contributions are welcome! If you have suggestions for improving this plugin or find any bugs, please open an issue or submit a pull request.

License:

This project is licensed under the MIT License. See the LICENSE file for more details.