Skip to main content

Writing custom formatters

A formatter is a function with the following signature:

/**
* @type {import('stylelint').Formatter}
*/
function formatter(results, returnValue) {
return "a string of formatted results";
}

Where the first argument (results) is an array of Stylelint result objects (type Array<StylelintResult>) in the form:

// A Stylelint result object
{
"source": "path/to/file.css", // The filepath or PostCSS identifier like <input css 1>
"errored": true, // This is `true` if at least one rule with an "error"-level severity triggered a warning
"warnings": [
// Array of rule problem warning objects, each like the following ...
{
"line": 3,
"column": 12,
"rule": "block-no-empty",
"severity": "error",
"text": "You should not have an empty block (block-no-empty)"
}
],
"deprecations": [
// Array of deprecation warning objects, each like the following ...
{
"text": "Feature X has been deprecated and will be removed in the next major version.",
"reference": "https://stylelint.io/docs/feature-x.md"
}
],
"invalidOptionWarnings": [
// Array of invalid option warning objects, each like the following ...
{
"text": "Invalid option X for rule Y"
}
],
"ignored": false // This is `true` if the file's path matches a provided ignore pattern
}

And the second argument (returnValue) is an object (type LinterResult) with one or more of the following keys:

{
"errored": false, // `true` if there were any warnings with "error" severity
"maxWarningsExceeded": {
// Present if Stylelint was configured with a `maxWarnings` count
"maxWarnings": 10,
"foundWarnings": 15
}
}

Passing arguments

You can use environmental variables in your formatter. For example, pass SKIP_WARNINGS:

SKIP_WARNINGS=true stylelint "*.css" --custom-formatter ./my-formatter.js

Alternatively, you can create a separate formatting program and pipe the output from the built-in JSON formatter into it:

stylelint -f json "*.css" | my-program-that-reads-JSON --option

stylelint.formatters

Stylelint's internal formatters are exposed publicly in stylelint.formatters.