stylelint-order: four rules for the order of your CSS

Four rules, four different kinds of order

The plugin pack is small, and the readme lists the rules with one line each, which is enough to see that they answer four distinct questions.

The order rule specifies the order of content within declaration blocks, which is the rule you use when you want your custom properties, then your declarations, then your nested rules, in a fixed sequence. The properties-order rule specifies the order of properties within declaration blocks, which is the one people usually mean when they say they want their styles sorted, and it takes an explicit list.

The properties-alphabetical-order rule does the same thing alphabetically, so you do not have to maintain a list at all. And the custom-properties-alphabetical-order rule applies the alphabetical treatment to custom properties, the CSS variables, separately from the other properties.

That last rule exists for a real reason. Custom properties are usually the ones a team wants in a stable, predictable place, often at the top of a block as a palette, while the ordinary properties below them follow a different convention. A single properties-order list would force you to interleave the two, and most people find that unreadable.

The rules are namespaced. Every rule from this pack has to be written with the order prefix, which is what lets it live in the same rules list as core Stylelint rules and as any other plugin, without name collisions.

Configuration is a plugin entry and a rules list

The usage section is two steps, and the second one is where the namespacing appears.

You install Stylelint itself if you have not, and then you install the plugin pack, both as development dependencies.

npm install stylelint --save-dev

npm install stylelint-order --save-dev

Then in the Stylelint configuration you add the plugin to the plugins array, and you add the rules you want to the rules list, with every rule from this pack namespaced with the order prefix.

"order/order": [

The example configuration shows two rules at once, one for the order of content within a block and one for the order of the properties, and the second takes the property names as a list. That list is the whole configuration surface, and it is the part of the tool that teams argue about, which is why the readme points at ready made configurations further down.

The order rule takes groups rather than individual names: in the example, custom properties means the group of custom property declarations, followed by the declarations, so you express a convention rather than list every property one by one.

Autofixing, and the three places it is careful

Every rule supports autofixing through the standard Stylelint fix flag, and the readme says that the sorting is done internally by a separate library.

stylelint --fix

What the readme is careful about is the limits of that fixing, and there are three of them.

Automatic sorting has limitations, and they are described for every rule if there are any, with a link to how comments are handled. Comments are the hard case for any sorting implementation, because a comment that explained a particular property has to travel with that property, and the behaviour differs depending on where the comment sits.

Second, CSS in JavaScript styles with template interpolation have limited autofixing, and the reason given is to avoid style corruption. That is a good default. A fixer that cannot safely reorder a stylesheet with interpolated values should refuse rather than guess, because a corrupted stylesheet is worse than an unsorted one.

Third, autofixing in Less syntax may work but is not officially supported. The distinction between may work and is supported is the kind of distinction a project only draws when it has had a bug report.

So the honest summary is that the fixer is safe on plain CSS, careful on embedded languages, and unpromised on Less, and the readme links the details rather than asking you to trust it.

The example configurations save the argument

There is a section of example configurations, and it exists because the property order is the part of this tool that is genuinely a matter of taste.

All the listed configurations have the properties-order rule configured with logical properties groups, and there are five of them. One is an idiomatic order configuration, one is the author's own order configuration, one is named after a style guide that many teams already follow, one is named after a logical property ordering standard, and one is a clean order configuration.

The mention of logical properties is the detail with teeth. Logical properties are the writing-mode aware equivalents of physical ones, so a margin-block-start is the logical version of a top margin, and a padding-inline-end is the logical version of a right padding. Ordering a stylesheet by logical property groups means the same block works in a left-to-right language and a right-to-left one, which is a real argument for sorting rather than an aesthetic one.

So the practical advice is to pick one of these rather than to write your own list, because these are the orderings that have been made to work with the sorting implementation, and a hand written list will hit the fixer's edge cases sooner.

There is also a small piece of history in the thanks section that explains why the pack exists in this shape. The properties-order and properties-alphabetical-order code and documentation were based on a rule that used to be part of Stylelint itself, the declaration block properties order rule, which was a core rule before Stylelint 8.0.0. When core rules were moved out into plugins, this pack became the home for that behaviour, and it has grown since.

The package, and a test setup built for syntax variants

The manifest is worth reading, because it says what the plugin supports and how carefully it is tested.

The package is MIT licensed, at version 8.1.2, and it is an ES module with a single entry point. It requires Node 20.19 or newer, and its peer dependency on Stylelint accepts two major lines, which tells you the plugin is being maintained against the current Stylelint while still working for people a version behind.

The runtime dependencies are two, and both are about parsing rather than linting. One is the CSS parser, and the other is the sorting library that does the actual work of reordering during autofix. That is a nicely layered design, because the rule logic and the sorting mechanics are separate concerns, and the second is a library the author also maintains and documents.

The development dependencies are the interesting part, because they show how the rules are tested. The test runner is Jest, but with a light runner and the Stylelint preset, so the tests use Stylelint's own test harness rather than a generic one. And there are three separate parser packages, one for HTML, one for Less and one for styled syntax, which is how the plugin tests the syntax variants whose fixing it says it cannot fully support.

The scripts follow the usual shape, with a lint that treats any warning as a failure, a fix script, a test, a watch mode and a coverage run. Husky installs the git hooks, and lint-staged runs the linter and the formatter on the staged files before a commit, so a change to a rule cannot be committed in a state where the repository's own lint fails.

How the project moves

The release history is short and shows a project that ships when there is something to ship.

Version 8.1.0 came out in March 2026, 8.1.1 two days later, and 8.1.2 in October, with the last push on the same day as that release and the repository not archived. So a minor version, a patch two days later, and then a gap of about seven months before the next one.

The pattern suggests a project that changes when the Stylelint ecosystem moves, which fits a plugin whose peer dependency spans two major lines of Stylelint. When a new Stylelint major lands, the plugin is updated to support it, and the version number moves.

The repository layout is consistent with a plugin of this size. There is an index file as the entry point, a rules directory with one directory per rule, each of which has its own documentation, and a utilities directory for the shared code between the rules. There is a changelog, a licence file, an editor configuration, a git attributes file, an ESLint configuration and a Prettier configuration.

The one thing a reader should take away is the division of labour. The rules themselves are thin, because the work of moving declarations around is done by the sorting library, and the rules are configuration surfaces over it. That is why the pack is small, why the example configurations matter so much, and why the fixer's limits are the interesting constraint rather than the rules themselves.

Editorial conclusion

stylelint-order suits a team that has decided the order of its declarations is a reviewable convention, because the autofixing means the convention can be enforced on existing code without a large manual diff. It is a poor fit if your ordering is a matter of taste, because a linter turns taste into a build failure. Before you enable it, read the autofixing limitations for your syntax, particularly if you use CSS in JavaScript or Less, and pick one of the example configurations rather than writing the property list yourself, since those are the ones that have been made to work with the sorting implementation.

Frequently asked questions

Official sources

1. hudochenkov/stylelint-order on GitHub
2. Issues
3. License: MIT
4. README
5. Releases