postcss-sort-media-queries

What is postcss-sort-media-queries?

The postcss-sort-media-queries package is a PostCSS plugin that sorts CSS media queries. It helps in organizing media queries in a specific order, which can be useful for maintaining a clean and efficient stylesheet.

What are postcss-sort-media-queries's main functionalities?

Sort Media Queries by Width

This feature sorts media queries in a mobile-first order, meaning smaller screen sizes will be prioritized over larger ones.

module.exports = {
  plugins: [
    require('postcss-sort-media-queries')({
      sort: 'mobile-first'
    })
  ]
};

Sort Media Queries by Custom Order

This feature sorts media queries in a desktop-first order, meaning larger screen sizes will be prioritized over smaller ones.

module.exports = {
  plugins: [
    require('postcss-sort-media-queries')({
      sort: 'desktop-first'
    })
  ]
};

Sort Media Queries by Specific Criteria

This feature allows you to sort media queries based on a custom function, providing flexibility in how media queries are ordered.

module.exports = {
  plugins: [
    require('postcss-sort-media-queries')({
      sort: function(a, b) {
        return a.localeCompare(b);
      }
    })
  ]
};

Other packages similar to postcss-sort-media-queries

css-mqpacker

css-mqpacker is a PostCSS plugin that packs same CSS media query rules into one media query rule. Unlike postcss-sort-media-queries, which focuses on sorting, css-mqpacker focuses on merging media queries to reduce redundancy.

postcss-combine-media-query

postcss-combine-media-query is a PostCSS plugin that combines matching media queries into one. It is similar to css-mqpacker but with a focus on combining rather than sorting.

postcss-merge-rules

postcss-merge-rules is a PostCSS plugin that merges adjacent rules by selectors and properties. While it doesn't specifically target media queries, it can help in reducing the overall size of the CSS by merging rules, which can indirectly affect media queries.

README

PostCSS Sort Media Queries

🌏 English ▫ O'zbek

PostCSS plugin for sorting and combining CSS media queries with mobile first / desktop first methodologies.

From 5.0.0 plugin support Media Feature Types: “range”

Table of Contents

• Online demo
• Examples
  • Mobile first sorting
  • Desktop first sorting
• Install
• Usage
• Options
  • sort
  • Custom sort function
  • Sort configuration
  • Only Top Level
• Changelog
• License
• Other PostCSS plugins
• Thanks 💪

Online demo

And here is the online demo

Examples

Mobile first sorting

before

@media screen and (max-width: 640px) {
  .head { color: #cfcfcf }
}
@media screen and (max-width: 768px) {
  .footer { color: #cfcfcf }
}
@media screen and (max-width: 640px) {
  .main { color: #cfcfcf }
}
@media screen and (min-width: 1280px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (width > 640px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (max-width: 640px) {
  .footer { color: #cfcfcf }
}

after

@media screen and (width > 640px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (min-width: 1280px) {
  .mobile-first { color: #cfcfcf }
}
@media screen and (max-width: 768px) {
  .footer { color: #cfcfcf }
}
@media screen and (max-width: 640px) {
  /* combined */
  .head { color: #cfcfcf }
  .main { color: #cfcfcf }
  .footer { color: #cfcfcf }
}

Desktop first sorting

before

@media screen and (width < 640px) {
  .header { color: #cdcdcd }
}
@media screen and (min-width: 760px) {
  .desktop-first { color: #cdcdcd }
}
@media screen and (width < 640px) {
  .main { color: #cdcdcd }
}
@media screen and (min-width: 1280px) {
  .desktop-first { color: #cdcdcd }
}
@media screen and (max-width: 760px) {
  .footer { color: #cdcdcd }
}
@media screen and (max-width: 640px) {
  .footer { color: #cdcdcd }
}

after

@media screen and (max-width: 760px) {
  .footer { color: #cdcdcd }
}
@media screen and (width < 640px) {
  /* combined */
  .header { color: #cdcdcd }
  .main { color: #cdcdcd }
  .footer { color: #cdcdcd }
}
@media screen and (min-width: 760px) {
  .desktop-first { color: #cdcdcd }
}
@media screen and (min-width: 1280px) {
  .desktop-first { color: #cdcdcd }
}

Install

First thing's, install the module:

npm install postcss postcss-sort-media-queries --save-dev

Usage

Check you project for existed PostCSS config: postcss.config.js in the project root, "postcss" section in package.json or postcss in bundle config.

If you already use PostCSS, add the plugin to plugins list:

module.exports = {
  plugins: [
+   require('postcss-sort-media-queries')({
+     sort: 'mobile-first', // default value
+   }),
    require('autoprefixer')
  ]
}

or with custom sort function

module.exports = {
  plugins: [
+   require('postcss-sort-media-queries')({
+     sort: function(a, b) {
+        // custom sorting function
+     }
+   }),
    require('autoprefixer')
  ]
}

If you do not use PostCSS, add it according to official docs and set this plugin in settings.

Options

Sorting works based on dutchenkoOleg/sort-css-media-queries function.

sort

This option support string or function values.

• {string} 'mobile-first' - (default) mobile first sorting
• {string} 'desktop-first' - desktop first sorting
• {function} your own sorting function

'mobile-first'

postcss([
  sortMediaQueries({
    sort: 'mobile-first' // default
  })
]).process(css);

'desktop-first'

postcss([
  sortMediaQueries({
    sort: 'desktop-first'
  })
]).process(css);

Custom sort function

postcss([
  sortMediaQueries({
    function(a, b) {
      return a.localeCompare(b);
    }
  })
]).process(css);

In this example, all your media queries will sort by A-Z order.

This sorting function is directly passed to Array#sort() method of an array of all your media queries.

Sort configuration

By this configuration you can control sorting behaviour.

postcss([
  sortMediaQueries({
    configuration: {
      unitlessMqAlwaysFirst: true, // or false
    }
  })
]).process(css);

Or alternatively create a sort-css-mq.config.json file in the root of your project. Or add property sortCssMQ: {} in your package.json.

Only Top Level

Sort only top level media queries to prevent eject nested media queries from parent node

postcss([
  sortMediaQueries({
    onlyTopLevel: true,
  })
]).process(css);

---

Changelog

See Releases history

License

MIT

Other PostCSS plugins

• postcss-momentum-scrolling - plugin for adding momentum style scrolling behavior (-webkit-overflow-scrolling:touch) for elements with overflow (scroll, auto) on iOS

Thanks

• Andrey Sitnik @ai
• Oleh Dutchenko @dutchenkoOleg
• Jakub Caban @Lustmored
• Dmytro Symonov @Kassaila
• Kai Falkowski @SassNinja
• Khayot Razzakov @Khayotbek1

Changelog

[5.2.0] 2023-05-30

• Add onlyTopLevel option prevent eject nested media queries from parent