vscode-stylelint

The official Visual Studio Code extension for Stylelint.

Currently tested against Stylelint 14-17. Untested versions may still work, but are not guaranteed to do so. See Stylelint Version Support for details.

Table of Contents

• Installation
  • Disable VS Code's Built-In Linters (optional)
• Usage
  • Commands
  • Actions
  • Problem Matchers
  • Extension Settings
• Stylelint Version Support
• Migrating
• Troubleshooting
• Contributing
• Licence

Installation

You can install the extension from the Command Palette:

1. Execute the Extensions: Install Extensions command
2. Type @id:stylelint.vscode-stylelint into the search form
3. Install the topmost one with the verified publisher mark.

For more details, you can read the VS Code's extension installation guide.

Disable VS Code's Built-In Linters (optional)

You can disable VS Code's built-in linters either in the user or workspace settings.

For example, to disable the built-in CSS, Less, and SCSS linters:

  "css.validate": false,
  "less.validate": false,
  "scss.validate": false

An example of duplicate error messages emitted by both the built-in linter and vscode-stylelint.

Usage

See the Stylelint getting started guide for more information.

The extension will automatically lint CSS and PostCSS documents (those with language identifiers css and postcss, respectively) once you create a Stylelint configuration file (or configure the Stylelint extension's settings) and install Stylelint.

You can see or change the current document's language in the bottom-right corner of the editor window.

You can use the stylelint.validate extension setting to lint additional languages.

For example, to additionally lint SCSS:

  "stylelint.validate": ["css", "postcss", "scss"],

Or to additionally lint CSS-in-JS in JSX and TSX:

  "stylelint.validate": ["css", "postcss", "javascriptreact", "typescriptreact"],

The extension first looks for a copy of Stylelint installed in the open workspace folder, then for a globally installed version if it can't find one. If neither can be found, it will not lint any documents.

Commands

The extension adds the following commands to the command palette:

• Fix all auto-fixable Problems - apply fixes to all automatically fixable problems
• Lint All Files - lint all files matching the stylelint.lintFiles.glob pattern in every workspace folder
• Lint Workspace Folder - lint all matching files in a single workspace folder
• Clear All Problems - clear all Stylelint diagnostics
• Restart Stylelint Server - restart the Stylelint LSP and runtime server
• Show Output Channel - open the Stylelint output panel

Actions

The extension provides an action that you can use with VS Code's editor.codeActionsOnSave setting.

editor.codeActionsOnSave

You can automatically fix all auto-fixable problems on save by setting the source.fixAll.stylelint property to explicit:

  "editor.codeActionsOnSave": {
    "source.fixAll.stylelint": "explicit"
  }

Or turn on auto fix for all providers, not just Stylelint:

  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit"
  }

You can also selectively disable Stylelint:

  "editor.codeActionsOnSave": {
    "source.fixAll": "explicit",
    "source.fixAll.stylelint": "never"
  }

You can also selectively enable and disable specific languages using VS Code's language-scoped settings. For example, to disable codeActionsOnSave for HTML files, use the following:

  "[html]": {
    "editor.codeActionsOnSave": {
      "source.fixAll.stylelint": "never"
    }
  }

Problem Matchers

The extension contributes problem matchers that can be used to parse Stylelint CLI output from VS Code tasks into the Problems panel.

Two problem matchers are available, corresponding to a selection of Stylelint's formatters:

• $stylelint-compact for the compact formatter
• $stylelint-unix for the unix formatter

For example, to lint all CSS files using a task with the compact formatter, set up a task like so:

// .vscode/tasks.json
{
  "version": "2.0.0",
  "tasks": [
    {
      "type": "npm",
      "script": "lint:stylelint",
      "problemMatcher": "$stylelint-compact"
    }
  ]
}

where lint:stylelint is a script running Stylelint with the compact formatter:

// package.json
{
  "scripts": {
    "lint:stylelint": "stylelint --formatter=compact \"**/*.css\""
  }
}

Note

Stylelint's default formatter uses multiline output, which VS Code's problem matcher system does not fully support. This is why you must use either the compact or unix formatter to use the problem matchers.

Extension Settings

Though relying on a Stylelint configuration file in your project is highly recommended, you can instead use the following extension settings:

stylelint.enable

Type: boolean
Default: true

Controls whether this extension is enabled or not.

stylelint.run

Type: "onSave" | "onType"
Default: "onType"

Controls when the linter runs.

• onType: Runs on each change as you type.
• onSave: Only runs after you save a document.

stylelint.logLevel

Type: "error" | "warn" | "info" | "debug"
Default: "info"

Controls the log level used by the Stylelint extension and language server. Restart the extension host or the window after changing the setting, since it's picked up at initialization.

stylelint.runtime

Type: string | null
Default: null

The location of the node binary to run Stylelint under. By default, the extension uses the Node.js runtime bundled with VS Code. Set this to use a different Node.js version on your system.

For example:

  "stylelint.runtime": "/usr/local/bin/node"

Changing this setting requires a server restart to take effect.

stylelint.execArgv

Type: string[] | null
Default: null

Additional exec argv arguments passed to the Node.js runtime.

For example:

  "stylelint.execArgv": ["--max_old_space_size=8192"]

Changing this setting requires a server restart to take effect.

stylelint.validate

Type: string[]
Default: ["css", "postcss"]

An array of language identifiers specifying which files to validate.

stylelint.snippet

Type: string[]
Default: ["css", "postcss"]

An array of language identifiers specifying which files to enable snippets for.

stylelint.stylelintPath

Type: string
Default: ""

Used to supply a custom path to the Stylelint module.

stylelint.packageManager

Type: "npm" | "yarn" | "pnpm"
Default: "npm"

Controls the package manager to be used to resolve the Stylelint library. This setting only has an effect if the Stylelint library is resolved globally. Valid values are "npm" or "yarn" or "pnpm".

stylelint.rules.customizations

Type: object[]
Default: []

An array of rule customizations that let you override the severity level of Stylelint rules. This is useful for downgrading errors to warnings, upgrading warnings to errors, or completely suppressing specific rules in the editor.

Each customization object has the following properties:

• rule: A string pattern matching the rule name. Supports wildcards and negation patterns:
  • Exact match: "color-named" matches only the color-named rule.
  • Wildcard: "color-*" matches all rules starting with color-.
  • Negation: "!color-*" matches all rules except those starting with color-.
• severity: The severity level to apply.
  • "error": Show as error (red underline).
  • "warn": Show as warning (yellow underline).
  • "info": Show as information (blue underline).
  • "off": Don't show the diagnostic.
  • "default": Use the original severity from Stylelint.
  • "downgrade": Convert errors to warnings, warnings to info messages.
  • "upgrade": Convert info to warnings, warnings to errors.

Customizations are applied in order, with later rules taking priority over earlier ones. This means that more general patterns should come before more specific ones for the specific rules to override the general ones.

Example:

{
  "stylelint.rules.customizations": [
    {
      "rule": "font-*",
      "severity": "info"
    },
    {
      "rule": "!color-*",
      "severity": "info"
    },
    {
      "rule": "declaration-block-*",
      "severity": "default"
    },
    {
      "rule": "comment-word-disallowed-list",
      "severity": "off"
    },
    {
      "rule": "color-named",
      "severity": "warn"
    }
  ]
}

stylelint.config

Type: Object
Default: null

Sets the Stylelint config option. Note that when this option is enabled, Stylelint doesn't load configuration files.

stylelint.configFile

Type: string
Default: ""

Sets the Stylelint configFile option. Path to a JSON, YAML, or JS file that contains your configuration object. Use this option if you don't want Stylelint to search for a configuration file.

stylelint.configBasedir

Type: string
Default: ""

Sets the Stylelint configBasedir option. The path to the directory to which relative paths defining "extends" and "plugins" are relative. Only necessary if these values are relative paths.

stylelint.customSyntax

Type: string
Default: ""

Sets the Stylelint customSyntax option, which points to a PostCSS syntax module. Must be either the package name or an absolute path to the module.

e.g.

  "stylelint.customSyntax": "sugarss"

You can use ${workspaceFolder} to refer to the folder opened in VS Code.

e.g.

  "stylelint.customSyntax": "${workspaceFolder}/custom-syntax.js"

stylelint.ignoreDisables

Type: boolean
Default: false

Sets the Stylelint ignoreDisables option. If true, Stylelint ignores stylelint-disable (e.g. /* stylelint-disable block-no-empty */) comments.

stylelint.ignorePath

Type: string
Default: ""

Sets the Stylelint ignorePath option. Path to a file containing patterns describing files to ignore. Use to override automatic .stylelintignore detection.

You can use ${workspaceFolder} to refer to the folder opened in VS Code.

e.g.

  "stylelint.ignorePath": "${workspaceFolder}/.gitignore"

stylelint.lintFiles.glob

Type: string
Default: "**/*.css"

The glob pattern used by the "Lint All Files" and "Lint Workspace Folder" commands to discover files. Adjust this if you lint SCSS, Less, or other file types.

e.g.

  "stylelint.lintFiles.glob": "**/*.{css,scss}"

stylelint.reportDescriptionlessDisables

Type: boolean
Default: false

Sets the Stylelint reportDescriptionlessDisables option. If true, Stylelint reports stylelint-disable comments without a description.

stylelint.reportNeedlessDisables

Type: boolean
Default: false

Sets the Stylelint reportNeedlessDisables option. If true, Stylelint reports errors for stylelint-disable comments that are not blocking a lint warning.

stylelint.reportInvalidScopeDisables

Type: boolean
Default: false

Sets the Stylelint reportInvalidScopeDisables option. If true, Stylelint reports errors for stylelint-disable comments referring to rules that don't exist within the configuration object.

Stylelint Version Support

We support all Stylelint versions that work without active maintenance burden. We drop support when maintaining compatibility causes bugs, blocks features, or adds meaningful complexity. Versions not listed above as tested may still work but are not officially supported.

When we do decide to drop support for a version, we will provide at least 3 months' notice with a deprecation warning before removal, giving users a predictable window to migrate.

Migrating

See the migration guide for instructions on how to migrate from older versions of the extension.

Troubleshooting

vscode-stylelint writes logs to the VS Code output panel:

You can enable more verbose log output by setting the logLevel extension setting or by running VS Code with the NODE_ENV environment variable set to development. You can do this on macOS and *nix by running:

NODE_ENV=development code

And on Windows by running:

cmd /C "set NODE_ENV=development&&code"

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for details.

Licence

MIT