eslint-plugin-styled-components-a11y

2.2.1 verified Sat Apr 25 auth: no javascript

An ESLint plugin that adds accessibility linting rules for styled-components, wrapping eslint-plugin-jsx-a11y to handle all seven methods styled-components uses to create components (styled.div, styled('div'), attrs, as prop, object syntax, etc.). Version 2.2.1 supports ESLint 3–9 and works with both legacy and flat configs. Unique in extending jsx-a11y to cover styled-components patterns without false negatives. Released under MIT, maintained by Brendan Morrell.

Common errors

error Error: Failed to load plugin 'styled-components-a11y' declared in '.eslintrc.json' ↓

cause Plugin not installed or peer dependency missing (eslint-plugin-jsx-a11y).

fix

Run npm install --save-dev eslint-plugin-styled-components-a11y eslint-plugin-jsx-a11y

error TypeError: Cannot read properties of undefined (reading 'recommended') ↓

cause Using flat config but the plugin is imported incorrectly (default import missing).

fix

Use import styledA11y from 'eslint-plugin-styled-components-a11y' then access styledA11y.flatConfigs.recommended

error ESLint: 'styled-components-a11y/rule-name' is not a valid rule name ↓

cause Rule name misspelled or not available (maybe using old rule names).

fix

Check the correct rule name from the plugin's rule list (e.g., 'styled-components-a11y/no-onchange').

Warnings

gotcha Styled-components v6 changed some internal APIs; older plugin versions may not detect all styled patterns correctly. ↓

fix Upgrade to v2.2.0+ which addresses styled-components v6 compatibility.

deprecated The `componentWithForwardedRef` rule no longer exists in recent versions; use `no-arrow-function-in-jsx` instead. ↓

fix Replace 'styled-components-a11y/componentWithForwardedRef' with 'styled-components-a11y/no-arrow-function-in-jsx'.

breaking Flat config support requires ESLint v9+; using flat config with ESLint v8 will result in errors. ↓

fix Ensure ESLint v9 is installed if using flat config; for ESLint v8, continue using legacy .eslintrc.

gotcha The plugin re-exports all rules from eslint-plugin-jsx-a11y but prefixed with 'styled-components-a11y/'. Enabling recommended ruleset may conflict with standalone jsx-a11y rules if both are used. ↓

fix Disable standalone jsx-a11y rules when using this plugin to avoid duplicate warnings.

gotcha The `as` prop is supported but only when used with styled-components; custom components using `as` without styled may not be linted. ↓

fix Ensure the component using `as` is created via styled() to trigger linting rules.

deprecated ESLint v8 is becoming legacy; future plugin releases may drop support for v8. ↓

fix Migrate to ESLint v9 to ensure continued compatibility.

Install

npm install eslint-plugin-styled-components-a11y

yarn add eslint-plugin-styled-components-a11y

pnpm add eslint-plugin-styled-components-a11y

Imports

default export

wrong

const styledA11y = require('eslint-plugin-styled-components-a11y')

correct

import styledA11y from 'eslint-plugin-styled-components-a11y'

Plugin uses ESM default export; CJS require works but import is preferred for flat config.

plugin in plugins object

wrong

plugins: ['styled-components-a11y']

correct

import styledA11y from 'eslint-plugin-styled-components-a11y';
plugins: { 'styled-components-a11y': styledA11y }

Flat config requires plugin object, not string array.

flatConfigs.recommended

wrong

export default [ 'plugin:styled-components-a11y/recommended' ]

correct

import styledA11y from 'eslint-plugin-styled-components-a11y';
export default [ styledA11y.flatConfigs.recommended ]

Flat config shareable configs are attached to the plugin object; the string syntax is for legacy config only.

Quickstart

Install the plugin and configure it with the recommended ruleset using either legacy .eslintrc or flat config.

npm install --save-dev eslint-plugin-styled-components-a11y eslint-plugin-jsx-a11y
# Legacy .eslintrc:
{
  "plugins": ["styled-components-a11y"],
  "extends": ["plugin:styled-components-a11y/recommended"]
}

# Flat config (eslint.config.js):
import styledA11y from 'eslint-plugin-styled-components-a11y';
export default [
  styledA11y.flatConfigs.recommended,
];