stylelint-declaration-block-order

Stylelint plugin which specifies the order of content within declaration blocks.

For specifying declarations order use stylelint's declaration-block-properties-order rule.

Installation

npm install stylelint-declaration-block-order

Usage

Add stylelint-declaration-block-order to your stylelint config plugins array, then add plugin/declaration-block-order to your rules, specifying your elements order.

Like so:

// .stylelintrc
{
    "plugins": [
        "stylelint-declaration-block-order"
    ],
    "rules": {
        // ...
        "plugin/declaration-block-order": [
            "custom-properties",
            "dollar-variables",
            "declarations",
            "rules",
            "at-rules"
        ],
        // ...
    }
}

Options

Primary option

["array", "of", "keywords", "or", "expanded", "at-rule", "objects"]

Within an order array, you can include:

• keywords:
  • custom-properties — Custom properties (e. g., --property: 10px;)
  • dollar-variables — Dollar variables (e. g., $variable)
  • declarations — CSS declarations (e. g., display: block)
  • rules — Nested rules (e. g., a { span {} })
  • at-rules — Nested at-rules (e. g., div { @media () {} })
• extended at-rules objects:

  {
      type: 'at-rule',
      name: 'include',
      parameter: 'hello',
      hasBlock: true
  }
  

Extended at-rules objects have different parameters and variations.

Object parameters:

• type: always "at-rule"
• name: string. E. g., name: "include" for @include
• parameter: string|regex. A string will be translated into a RegExp — new RegExp(yourString) — so be sure to escape properly. E. g., parameter: "icon" for @include icon(20px);
• hasBlock: boolean. E. g., hasBlock: true for @include icon { color: red; } and not for @include icon;

Always specify name if parameter is specified.

Matches all at-rules:

{
    type: 'at-rule'
}

Or keyword at-rules.

Matches all at-rules, which have nested elements:

{
    type: 'at-rule',
    hasBlock: true
}

Matches all at-rules with specific name:

{
    type: 'at-rule',
    name: 'media'
}

Matches all at-rules with specific name, which have nested elements:

{
    type: 'at-rule',
    name: 'media',
    hasBlock: true
}

Matches all at-rules with specific name and parameter:

{
    type: 'at-rule',
    name: 'include',
    parameter: 'icon'
}

Matches all at-rules with specific name and parameter, which have nested elements:

{
    type: 'at-rule',
    name: 'include',
    parameter: 'icon',
    hasBlock: true
}

Each described above variant has more priority than its previous variant. For example, { type: 'at-rule', name: 'media' } will be applied to an element if both { type: 'at-rule', name: 'media' } and { type: 'at-rule', hasBlock: true } can be applied to an element.

By default, unlisted elements will be ignored. So if you specify an array and do not include declarations, that means that all declarations can be included before or after any other element. This can be changed with the unspecified option (see below).

Optional secondary option

unspecified: "top"|"bottom"|"ignore"

Thes option only applies if you've defined your own array of elements.

Default behavior is the same as "ignore": an unspecified element can appear before or after any other property.

With "top", unspecified elements are expected before any specified properties. With "bottom", unspecified properties are expected after any specified properties.

Examples

Given:

["custom-properties", "dollar-variables", "declarations", "rules", "at-rules"]

The following patterns are considered warnings:

a {
    top: 0;
    --height: 10px;
    color: pink;
}

a {
    @media (min-width: 100px) {}
    display: none;
}

The following patterns are not considered warnings:

a {
    --width: 10px;
    $height: 20px;
    display: none;
    span {}
    @media (min-width: 100px) {}
}

a {
    --height: 10px;
    color: pink;
    top: 0;
}

---

Given:

[
    {
        type: 'at-rule',
        name: 'include',
    },
    {
        type: 'at-rule',
        name: 'include',
        hasBlock: true
    },
    {
        type: 'at-rule',
        hasBlock: true
    },
    {
        type: 'at-rule',
    }
]

The following patterns are considered warnings:

a {
    @include hello {
        display: block;
    }
    @include hello;
}

a {
    @extend .something;
    @media (min-width: 10px) {
        display: none;
    }
}

The following patterns are not considered warnings:

a {
    @include hello;
    @include hello {
        display: block;
    }
    @media (min-width: 10px) {
        display: none;
    }
    @extend .something;
}

a {
    @include hello {
        display: block;
    }
    @extend .something;
}

---

Given:

[
    {
        type: 'at-rule',
        name: 'include',
        hasBlock: true
    },
    {
        type: 'at-rule',
        name: 'include',
        parameter: 'icon',
        hasBlock: true
    },
    {
        type: 'at-rule',
        name: 'include',
        parameter: 'icon'
    }
]

The following patterns are considered warnings:

a {
    @include icon {
        display: block;
    }
    @include hello {
        display: none;
    }
    @include icon;
}

a {
    @include icon;
    @include icon {
        display: block;
    }
}

The following patterns are not considered warnings:

a {
    @include hello {
        display: none;
    }
    @include icon {
        display: block;
    }
    @include icon;
}

a {
    @include hello {
        display: none;
    }
    @include icon;
}

---

Given:

[
    'custom-properties',
    {
        type: 'at-rule',
        hasBlock: true,
    },
    'declarations'
]

The following patterns are considered warnings:

a {
    @media (min-width: 10px) {
        display: none;
    }
    --height: 10px;
    width: 20px;
}

a {
    width: 20px;
    @media (min-width: 10px) {
        display: none;
    }
    --height: 10px;
}

a {
    width: 20px;
    @media (min-width: 10px) {
        display: none;
    }
}

The following patterns are not considered warnings:

a {
    --height: 10px;
    @media (min-width: 10px) {
        display: none;
    }
    width: 20px;
}

a {
    @media (min-width: 10px) {
        display: none;
    }
    width: 20px;
}

a {
    --height: 10px;
    width: 20px;
}

---

Given:

[
    [
        "declarations"
    ],
    {
        unspecified: "ignore"
    }
]

The following patterns are not considered warnings:

a {
    --height: 10px;
    display: none;
    $width: 20px;
}

a {
    --height: 10px;
    $width: 20px;
    display: none;
}

a {
    display: none;
    --height: 10px;
    $width: 20px;
}

---

Given:

[
    [
        "declarations"
    ],
    {
        unspecified: "top"
    }
]

The following patterns are considered warnings:

a {
    display: none;
    --height: 10px;
    $width: 20px;
}

a {
    --height: 10px;
    display: none;
    $width: 20px;
}

The following patterns are not considered warnings:

a {
    --height: 10px;
    $width: 20px;
    display: none;
}

a {
    $width: 20px;
    --height: 10px;
    display: none;
}

---

Given:

[
    [
        "declarations"
    ],
    {
        unspecified: "bottom"
    }
]

The following patterns are considered warnings:

a {
    --height: 10px;
    $width: 20px;
    display: none;
}

a {
    --height: 10px;
    display: none;
    $width: 20px;
}

The following patterns are not considered warnings:

a {
    display: none;
    --height: 10px;
    $width: 20px;
}

a {
    display: none;
    $width: 20px;
    --height: 10px;
}