ESLint CSS Language Plugin

Overview

This package contains a plugin that allows you to natively lint CSS files using ESLint.

Important: This plugin requires ESLint v9.6.0 or higher and you must be using the new configuration system.

Installation

For Node.js and compatible runtimes:

npm install @eslint/css -D
# or
yarn add @eslint/css -D
# or
pnpm install @eslint/css -D
# or
bun install @eslint/css -D

For Deno:

deno add @eslint/css

Configurations

Configuration Name	Description
recommended	Enables all recommended rules.

In your eslint.config.js file, import @eslint/css and include the recommended config:

// eslint.config.js
import css from "@eslint/css";

export default [
	// lint CSS files
	{
		files: ["**/*.css"],
		language: "css/css",
		...css.configs.recommended,
	},

	// your other configs here
];

Rules

Rule Name	Description	Recommended
no-duplicate-imports	Disallow duplicate @import rules	yes
no-empty-blocks	Disallow empty blocks	yes
no-invalid-at-rules	Disallow invalid at-rules	yes
no-invalid-properties	Disallow invalid properties	yes

Note: This plugin does not provide formatting rules. We recommend using a source code formatter such as Prettier for that purpose.

In order to individually configure a rule in your eslint.config.js file, import @eslint/css and configure each rule with a prefix:

// eslint.config.js
import css from "@eslint/css";

export default [
	{
		files: ["**/*.css"],
		plugins: {
			css,
		},
		language: "css/css",
		rules: {
			"css/no-empty-blocks": "error",
		},
	},
];

You can individually config, disable, and enable rules in CSS using comments, such as:

/* eslint css/no-empty-blocks: error */

/* eslint-disable css/no-empty-blocks -- this one is ok */
a {
}
/* eslint-enable css/no-empty-blocks */

b { /* eslint-disable-line css/no-empty-blocks */
}

/* eslint-disable-next-line css/no-empty-blocks */
em {
}

Languages

Language Name	Description
css	Parse CSS stylesheets.

In order to individually configure a language in your eslint.config.js file, import @eslint/css and configure a language:

// eslint.config.js
import css from "@eslint/css";

export default [
	{
		files: ["**/*.css"],
		plugins: {
			css,
		},
		language: "css/css",
		rules: {
			"css/no-empty-blocks": "error",
		},
	},
];

By default, the CSS parser runs in strict mode, which reports all parsing errors. If you'd like to allow recoverable parsing errors (those that the browser automatically fixes on its own), you can set the tolerant option to true:

// eslint.config.js
import css from "@eslint/css";

export default [
	{
		files: ["**/*.css"],
		plugins: {
			css,
		},
		language: "css/css",
		languageOptions: {
			tolerant: true,
		},
		rules: {
			"css/no-empty-blocks": "error",
		},
	},
];

Setting tolerant to true is necessary if you are using custom syntax, such as PostCSS plugins, that aren't part of the standard CSS syntax.

License

Apache 2.0

Sponsors

The following companies, organizations, and individuals support ESLint's ongoing maintenance and development. Become a Sponsor to get your logo on our READMEs and website.

Platinum Sponsors

Gold Sponsors

Silver Sponsors

Bronze Sponsors

Technology Sponsors

Technology sponsors allow us to use their products and services for free as part of a contribution to the open source ecosystem and our work.