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.15.0 or higher and you must be using the new configuration system.

Prequisites

In order to use the ESLint CSS plugin, you must have the following installed:

1. Node.js
2. ESLint

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 add @eslint/css -D

For Deno (experimental):

deno add jsr:@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 { defineConfig } from "eslint/config";
import css from "@eslint/css";

export default defineConfig([
	// lint CSS files
	{
		files: ["**/*.css"],
		language: "css/css",
		plugins: { css },
		extends: ["css/recommended"],
	},

	// your other configs here
]);

Rules

| Rule Name | Description | Recommended | | :----------------------------------------------------------------------------------- | :---------------------------------------------------- | :-------------: | | font-family-fallbacks | Enforce use of fallback fonts and a generic font last | yes | | no-duplicate-imports | Disallow duplicate @import rules | yes | | no-duplicate-keyframe-selectors | Disallow duplicate selectors within keyframe blocks | yes | | no-empty-blocks | Disallow empty blocks | yes | | no-important | Disallow !important flags | yes | | no-invalid-at-rule-placement | Disallow invalid placement of at-rules | yes | | no-invalid-at-rules | Disallow invalid at-rules | yes | | no-invalid-named-grid-areas | Disallow invalid named grid areas | yes | | no-invalid-properties | Disallow invalid properties | yes | | no-unmatchable-selectors | Disallow unmatchable selectors | yes | | prefer-logical-properties | Enforce the use of logical properties | no | | relative-font-units | Enforce the use of relative font units | no | | selector-complexity | Disallow and limit CSS selectors | no | | use-baseline | Enforce the use of baseline features | yes | | use-layers | Require use of layers | no |

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 { defineConfig } from "eslint/config";
import css from "@eslint/css";

export default defineConfig([
	{
		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 { defineConfig } from "eslint/config";
import css from "@eslint/css";

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

Tolerant Mode

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 { defineConfig } from "eslint/config";
import css from "@eslint/css";

export default defineConfig([
	{
		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.

Configuring Custom Syntax

The CSS lexer comes prebuilt with a set of known syntax for CSS that is used in rules like no-invalid-properties to validate CSS code. While this works for most cases, there may be cases when you want to define your own extensions to CSS, and this can be done using the customSyntax language option.

The customSyntax option is an object that uses the CSSTree format for defining custom syntax, which allows you to specify at-rules, properties, and some types. For example, suppose you'd like to define a custom at-rule that looks like this:

@my-at-rule "hello world!";

You can configure that syntax as follows:

// eslint.config.js
import { defineConfig } from "eslint/config";
import css from "@eslint/css";

export default defineConfig([
	{
		files: ["**/*.css"],
		plugins: {
			css,
		},
		language: "css/css",
		languageOptions: {
			customSyntax: {
				atrules: {
					"my-at-rule": {
						prelude: "<string>",
					},
				},
			},
		},
		rules: {
			"css/no-empty-blocks": "error",
		},
	},
]);

Configuring Tailwind Syntax

Tailwind specifies some extensions to CSS that will otherwise be flagged as invalid by the rules in this plugin. To properly parse Tailwind-specific syntax, install the tailwind-csstree package:

npm i tailwind-csstree --save-dev

Then include it in your configuration using languageOptions.customSyntax:

// eslint.config.js
import { defineConfig } from "eslint/config";
import css from "@eslint/css";
import { tailwind4 } from "tailwind-csstree";

export default defineConfig([
	{
		files: ["**/*.css"],
		plugins: {
			css,
		},
		language: "css/css",
		languageOptions: {
			customSyntax: tailwind4,
		},
		rules: {
			"css/no-empty-blocks": "error",
		},
	},
]);

Editor and IDE Setup

Visual Studio Code

First, ensure you have the ESLint plugin installed.

Then, edit eslint.validate in your settings.json file to include css:

{
	"eslint.validate": ["css"]
}

JetBrains WebStorm

For any JetBrains WebStorm, configure the ESLint scope to include css, such as:

**/*.{js,ts,jsx,tsx,cjs,cts,mjs,mts,html,vue,css}

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.