eslint-plugin-styled-components-order

eslint-plugin-styled-components-order

Automatically enforce a consistent order for CSS declarations inside styled-components tagged templates. Both rules are autofixable and support nested selectors, at-rules, interpolated values, the css helper, .attrs(), intrinsic elements, and custom components.

Requirements

• Node.js 20.19 or newer
• ESLint 8.57 or newer

Installation

npm install --save-dev eslint eslint-plugin-styled-components-order

Configuration

Choose one ordering strategy. The recommended preset uses alphabetical order.

Flat config

// eslint.config.js
const styledComponentsOrder = require("eslint-plugin-styled-components-order");

module.exports = [
  styledComponentsOrder.configs["flat/recommended"],
  // Or: styledComponentsOrder.configs["flat/concentric"],
];

To configure a rule directly:

const styledComponentsOrder = require("eslint-plugin-styled-components-order");

module.exports = [
  {
    plugins: {
      "styled-components-order": styledComponentsOrder,
    },
    rules: {
      "styled-components-order/sort-declarations-alphabetically": "error",
    },
  },
];

Legacy eslintrc

{
  "extends": ["plugin:styled-components-order/recommended"]
}

For concentric ordering, use "plugin:styled-components-order/concentric" instead.

Rules

sort-declarations-alphabetically

Sorts declarations by property name.

const Button = styled.button`
  color: white;
  display: inline-flex;
  padding: 0.5rem 1rem;
`;

sort-declarations-concentrically

Sorts declarations by structural impact, then from outside-in within the box model. The order is: custom properties; generated content; positioning and layout; display and visibility; clipping; animation; box model; backgrounds; typography; interaction; and nested selectors or at-rules. Related property families stay together, physical longhands use top-right-bottom-left order, and unknown properties are placed last alphabetically.

const Card = styled.article`
  --card-background: white;
  position: relative;
  display: grid;
  margin: 1rem;
  border: 1px solid;
  background: var(--card-background);
  color: black;
`;

Run ESLint with --fix to reorder declarations automatically:

npx eslint . --fix

Supported syntax

styled.div`...`;
styled(Component)`...`;
styled.div.attrs({ role: "button" })`...`;
css`...`;

Declarations inside nested selectors and block at-rules are sorted independently. JavaScript interpolations are preserved exactly as written. Templates containing invalid CSS are left untouched.

Development

npm install
npm run check

The check command runs ESLint, the Node.js test suite, and Prettier's format check. Use npm run format to apply formatting.

Commits must follow the Conventional Commits format. Validate a commit message with:

echo "feat: add a feature" | npm run commitlint

License

Apache-2.0