PostCSS Include Media

PostCSS plugin to output css @media definitions based on SASS mixin include-media format

Features

• Flexible declaration of breakpoints
• Smart support for media types
• On-the-fly breakpoints
• Supports most postcss plugins
• Postcss nesting plugin is a dependency to allow nesting of rules

Contents

• Install
• Options
• Examples
• Credits

Install

Step 1: Install plugins:

npm install --save-dev postcss postcss-nesting postcss-include-media

Step 2: 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 do not use PostCSS, add it according to official docs and set this plugin in settings.

Step 3: Add the plugin to plugins list:

+ const postcssIncludeMedia = require('postcss-include-media');

module.exports = {
  plugins: [
+   require('postcss-nesting'),
+   postcssIncludeMedia(),
    require('autoprefixer')
  ]
}

Options

breakpoints

If you want to change them or add more, you can simply re-declare breakpoints using the Sass map syntax.

type Record<key: string>

optional: true

defaults:

{ phone: '320px', tablet: '768px', desktop: '1024px' }

usage:

postcssIncludeMedia({
    breakpoints: {
        md: '700px',
        xl: '1200px,
    }
}),

mediaExpressions

Media types and static expressions are optional and automatically deferred. The list of media types can be modified by declaring mediaExpressions.

Expressions containing logical disjunctions, such as Chris Coyier's retina declaration, are correctly handled, even when combined with other media types or breakpoints.

type Record<key: string>

optional: true

defaults:

{
    screen: 'screen',
    print: 'print',
    all: 'all',
    handheld: 'handheld',
    landscape: '(orientation: landscape)',
    portrait: '(orientation: portrait)',
    retina2x: '(-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi), (min-resolution: 2dppx)',
    retina3x: '(-webkit-min-device-pixel-ratio: 3), (min-resolution: 350dpi), (min-resolution: 3dppx)',
}

usage:

postcssIncludeMedia({
    mediaExpressions: {
        retina: '(-webkit-min-device-pixel-ratio: 2)',
    }
}),

unitIntervals

Defines a number to be added or subtracted from each unit when declaring breakpoints with inclusive/exclusive intervals

type Record<key: number>

optional: true

defaults:

{
    px: 1,
    em: 0.01,
    rem: 0.1,
    '': 0,
}

usage:

postcssIncludeMedia({
    unitIntervals: {
        '%': 1,
    }
}),

ruleName

Defines a the rule name you wish to use for the detection of breakpoints. EG for @include media('>phone') set ruleName: 'include media'. While this is supported by the plugin, its not recommended, as could cause issues with other plugins.

type string

optional: true

defaults:

'include-media'

usage:

// allows rules to be used
// @banana ('>=md') { .test { content: '' } }
postcssIncludeMedia({
    ruleName: 'banana'
}),

Examples

Input

@include-media('>=phone') {
    .foo {
        /* Input example */
    }
}

@include-media('<desktop') {
    .bar {
        /* Input example */
    }
}

Output

@media (min-width: 320px) {
    .foo {
        /* Output example */
    }
}

@media (max-width: 1023px) {
    .bar {
        /* Input example */
    }
}

Input

@include-media('>123px') {
    .foo {
        /* Input example */
    }
}

Output

@media (min-width: 124px) {
    .foo {
        /* Output example */
    }
}

Input

@include-media('>=desktop', 'retina2x') {
    .foo {
        /* Input example */
    }
}

Output

@media (min-width: 1024px) and (-webkit-min-device-pixel-ratio: 2), (min-resolution: 192dpi), (min-resolution: 2dppx)  {
    .foo {
        /* Output example */
    }
}

Credits

Credit to the original Authors of include-media both Eduardo Boucas and Kitty Giraudel