customize.md

Customizing

The standard config turns on about half of the built-in rules. Stylelint is capable of so much more. We recommend using the standard config as a foundation and building on top of it.

You can use the other half of the built-in rules to:

• ensure even more consistency by disallowing things
• manage complexity in your code by setting limits

These conventions are typically specific to you and your project.

There's a lot you can do. For example, if you only want to allow:

• %, deg, px, rem, ms units generally
• px for borders
• rem for paddings and gaps

You can use the unit-allowed-list and declaration-property-unit-allowed-list rules:

{
  "extends": ["stylelint-config-standard"],
+ "rules": {
+   "declaration-property-unit-allowed-list": {
+     "/^border/": ["px"],
+     "/^padding|^gap/": ["rem"]
+   },
+   "unit-allowed-list": ["%", "deg", "px", "rem", "ms"]
+ }
}

Or you can enforce the hsl() color notation using the color-named, color-no-hex,function-disallowed-list rules:

{
  "extends": ["stylelint-config-standard"],
+ "rules": {
+   "color-named": "never",
+   "color-no-hex": true,
+   "function-disallowed-list": ["rgb", "hwb", "lch"]
+ }
}

Or you can limit the number of ID selectors using the selector-max-id rule:

{
  "extends": ["stylelint-config-standard"],
+ "rules": {
+   "selector-max-id": 0
+ }
}

These are just some of the things you can do with the built-in rules. It's possible to configure them to enforce strict conventions and keep your CSS under control.

Custom rules

In addition to the built-in rules, there are custom rules that you can plug into Stylelint.

Custom rules are typically written by communities to support methodologies, toolsets, non-standard CSS features, or very specific use cases.

You can add custom rules to your config by extending a shared config that includes them or by using a plugin directly. For example, you can order your properties by extending the recess order config, which includes the order plugin:

{
  "extends": [
    "stylelint-config-standard"
+   "stylelint-config-recess-order"
  ]
}

Or you can use the plugin directly if, for example, you want to alphabetize your properties:

{
  "extends": ["stylelint-config-standard"],
+ "plugins": ["stylelint-order"],
+ "rules": {
+   "order/properties-alphabetical-order": true
+ }
}

Custom rules do all sorts; from enforcing strict BEM conventions to strict scales for numeric values. You'll find more shared configs and plugins of custom rules listed in Awesome Stylelint.

You can also write your own custom rules within a plugin. This is particularly useful if you have specific needs or conventions you want to enforce.

Strictness

We recommend you craft a config that strictly enforces your conventions and then use configuration comments to disable specific rules when needed. You needn't shy away from using them as they are an integral part of Stylelint.

You can use the report* properties in your config to ensure your comments aren't useless and descriptionless:

{
  "extends": ["stylelint-config-standard"],
+ "reportDescriptionlessDisables": true,
+ "reportInvalidScopeDisables": true,
+ "reportNeedlessDisables": true
}

Each of these properties is configurable if you need to add exceptions to them.

You can also use the reportDisables secondary property to disallow disables on a per-rule basis.

Using Stylelint

You can use our Visual Studio Code extension, or one of the other integrations listed in Awesome Stylelint, to get instant feedback in your code editor. This is the quickest way to see and resolve problems.

You don't have to use the CLI either; we also provide a Node.js API, or you can use one of the other integrations or task runners listed in Awesome Stylelint.

Whichever you choose, there are many options in Stylelint that you can use to customize how Stylelint works. For example, you'll likely want to use the --fix option to automatically fix as many problems as possible:

npx stylelint "**/*.css" --fix

You may also want to look into the:

• --cache option to improve performance
• --formatter option to customize the output