stylelint-declaration-block-order v0.2.0
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:
```js { 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;
}