.config/coc/extensions/node_modules/coc-prettier/node_modules/autoprefixer/README.md

   1 # Autoprefixer [![Build Status][ci-img]][ci]
   2
   3 <img align="right" width="94" height="71"
   4      src="http://postcss.github.io/autoprefixer/logo.svg"
   5      title="Autoprefixer logo by Anton Lovchikov">
   6
   7 [PostCSS] plugin to parse CSS and add vendor prefixes to CSS rules using values
   8 from [Can I Use]. It is [recommended] by Google and used in Twitter and Taobao.
   9
  10 Write your CSS rules without vendor prefixes (in fact, forget about them
  11 entirely):
  12
  13 ```css
  14 :fullscreen a {
  15     display: flex;
  16 }
  17 ```
  18
  19 Autoprefixer will use the data based on current browser popularity and property
  20 support to apply prefixes for you. You can try the [interactive demo]
  21 of Autoprefixer.
  22
  23 ```css
  24 :-webkit-full-screen a {
  25     display: -webkit-box;
  26     display: flex;
  27 }
  28 :-moz-full-screen a {
  29     display: flex;
  30 }
  31 :-ms-fullscreen a {
  32     display: -ms-flexbox;
  33     display: flex;
  34 }
  35 :fullscreen a {
  36     display: -webkit-box;
  37     display: -ms-flexbox;
  38     display: flex;
  39 }
  40 ```
  41
  42 Twitter account for news and releases: [@autoprefixer].
  43
  44 <a href="https://evilmartians.com/?utm_source=autoprefixer">
  45 <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
  46 </a>
  47
  48 [interactive demo]: http://autoprefixer.github.io/
  49 [@autoprefixer]:    https://twitter.com/autoprefixer
  50 [recommended]:      https://developers.google.com/web/tools/setup/setup-buildtools#dont_trip_up_with_vendor_prefixes
  51 [Can I Use]:        http://caniuse.com/
  52 [PostCSS]:          https://github.com/postcss/postcss
  53 [ci-img]:           https://travis-ci.org/postcss/autoprefixer.svg
  54 [ci]:               https://travis-ci.org/postcss/autoprefixer
  55
  56 ## Features
  57
  58 ### Write Pure CSS
  59
  60 Working with Autoprefixer is simple: just forget about vendor prefixes
  61 and write normal CSS according to the latest W3C specs. You don’t need
  62 a special language (like Sass) or remember where you must use mixins.
  63
  64 Autoprefixer supports selectors (like `:fullscreen` and `::selection`),
  65 unit function (`calc()`), at‑rules (`@supports` and `@keyframes`)
  66 and properties.
  67
  68 Because Autoprefixer is a postprocessor for CSS,
  69 you can also use it with preprocessors such as Sass, Stylus or LESS.
  70
  71 ### Flexbox, Filters, etc.
  72
  73 Just write normal CSS according to the latest W3C specs and Autoprefixer
  74 will produce the code for old browsers.
  75
  76 ```css
  77 a {
  78     display: flex;
  79 }
  80 ```
  81
  82 compiles to:
  83
  84 ```css
  85 a {
  86     display: -webkit-box;
  87     display: -webkit-flex;
  88     display: -ms-flexbox;
  89     display: flex;
  90 }
  91 ```
  92
  93 Autoprefixer has [27 special hacks] to fix web browser differences.
  94
  95 [27 special hacks]: https://github.com/postcss/autoprefixer/tree/master/lib/hacks
  96
  97 ### Only Actual Prefixes
  98
  99 Autoprefixer utilizes the most recent data from [Can I Use]
 100 to add only necessary vendor prefixes.
 101
 102 It also removes old, unnecessary prefixes from your CSS
 103 (like `border-radius` prefixes, produced by many CSS libraries).
 104
 105 ```css
 106 a {
 107     -webkit-border-radius: 5px;
 108             border-radius: 5px;
 109 }
 110 ```
 111
 112 compiles to:
 113
 114 ```css
 115 a {
 116     border-radius: 5px;
 117 }
 118 ```
 119
 120 [Can I Use]: http://caniuse.com/
 121
 122 ## Browsers
 123
 124 Autoprefixer uses [Browserslist], so you can specify the browsers
 125 you want to target in your project by queries like `last 2 versions`
 126 or `> 5%`.
 127
 128 The best way to provide browsers is `.browserslistrc` config
 129 or `package.json` with `browserslist` key. Put it in your project root.
 130
 131 We recommend to avoid Autoprefixer option and use `.browserslistrc` config
 132 or `package.json`. In this case browsers will be shared with other tools
 133 like [babel-preset-env] or [Stylelint].
 134
 135 See [Browserslist docs] for queries, browser names, config format,
 136 and default value.
 137
 138 [Browserslist docs]: https://github.com/ai/browserslist#queries
 139 [babel-preset-env]:  https://github.com/babel/babel-preset-env
 140 [Browserslist]:      https://github.com/ai/browserslist
 141 [Stylelint]:         http://stylelint.io/
 142
 143 ## Outdated Prefixes
 144
 145 By default, Autoprefixer also removes outdated prefixes.
 146
 147 You can disable this behavior with the `remove: false` option. If you have
 148 no legacy code, this option will make Autoprefixer about 10% faster.
 149
 150 Also, you can set the `add: false` option. Autoprefixer will only clean outdated
 151 prefixes, but will not add any new prefixes.
 152
 153 Autoprefixer adds new prefixes between any unprefixed properties and already
 154 written prefixes in your CSS. If it will break the expected prefixes order,
 155 you can clean all prefixes from your CSS and then
 156 add the necessary prefixes again:
 157
 158 ```js
 159 var cleaner  = postcss([ autoprefixer({ add: false, browsers: [] }) ]);
 160 var prefixer = postcss([ autoprefixer ]);
 161
 162 cleaner.process(css).then(function (cleaned) {
 163     return prefixer.process(cleaned.css);
 164 }).then(function (result) {
 165     console.log(result.css);
 166 });
 167 ```
 168
 169 ## FAQ
 170
 171 #### No prefixes in production
 172
 173 Many other tools contain Autoprefixer. For example, webpack uses Autoprefixer
 174 to minify CSS by cleaning unnecessary prefixes.
 175
 176 If you set browsers list to Autoprefixer by `browsers` option, only first
 177 Autoprefixer will know your browsers. Autoprefixer inside webpack will use
 178 default browsers list. As result, webpack will remove prefixes, that first
 179 Autoprefixer added.
 180
 181 You need to put your browsers to [`browserslist` config] in project root —
 182 as result all tools (Autoprefixer, cssnano, doiuse, cssnext) will use same
 183 browsers list.
 184
 185 [`browserslist` config]: https://github.com/ai/browserslist#config-file
 186
 187 #### What is unprefixed version for `-webkit-min-device-pixel-ratio`?
 188
 189 ```css
 190 @media (min-resolution: 2dppx) {
 191     .image {
 192         background-image: url(image@2x.png);
 193     }
 194 }
 195 ```
 196
 197 Will be compiled to:
 198
 199 ```css
 200 @media (-webkit-min-device-pixel-ratio: 2),
 201        (-o-min-device-pixel-ratio: 2/1),
 202        (min-resolution: 2dppx) {
 203     .image {
 204         background-image: url(image@2x.png);
 205     }
 206 }
 207 ```
 208
 209 #### Does it add polyfills?
 210
 211 No. Autoprefixer only adds prefixes.
 212
 213 Most new CSS features will require client side JavaScript to handle a new
 214 behavior correctly.
 215
 216 Depending on what you consider to be a “polyfill”, you can take a look at some
 217 other tools and libraries. If you are just looking for syntax sugar,
 218 you might take a look at:
 219
 220 - [Oldie], a PostCSS plugin that handles some IE hacks (opacity, rgba, etc).
 221 - [postcss-flexbugs-fixes], a PostCSS plugin to fix flexbox issues.
 222 - [cssnext], a tool that allows you to write standard CSS syntax non-implemented
 223   yet in browsers (custom properties, custom media, color functions, etc).
 224
 225 [postcss-flexbugs-fixes]: https://github.com/luisrudge/postcss-flexbugs-fixes
 226 [cssnext]:                https://github.com/MoOx/postcss-cssnext
 227 [Oldie]:                  https://github.com/jonathantneal/oldie
 228
 229 #### Why doesn’t Autoprefixer add prefixes to `border-radius`?
 230
 231 Developers are often surprised by how few prefixes are required today.
 232 If Autoprefixer doesn’t add prefixes to your CSS, check if they’re still
 233 required on [Can I Use].
 234
 235 There is a [list with all supported] properties, values, and selectors.
 236
 237 [list with all supported]: https://github.com/postcss/autoprefixer/wiki/support-list
 238 [Can I Use]:               http://caniuse.com/
 239
 240 #### Why Autoprefixer uses unprefixed properties in `@-webkit-keyframes`?
 241
 242 Browser teams can remove some prefixes before others. So we try to use
 243 all combinations of prefixed/unprefixed values.
 244
 245 #### How to work with legacy `-webkit-` only code?
 246
 247 Autoprefixer needs unprefixed property to add prefixes. So if you only
 248 wrote `-webkit-gradient` without W3C’s `gradient`,
 249 Autoprefixer will not add other prefixes.
 250
 251 But [PostCSS] has a plugins to convert CSS to unprefixed state.
 252 Use [postcss-unprefix] before Autoprefixer.
 253
 254 [postcss-unprefix]: https://github.com/gucong3000/postcss-unprefix
 255
 256 #### Does Autoprefixer add `-epub-` prefix?
 257
 258 No, Autoprefixer works only with browsers prefixes from Can I Use.
 259 But you can use [postcss-epub](https://github.com/Rycochet/postcss-epub)
 260 for prefixing ePub3 properties.
 261
 262 #### Why doesn’t Autoprefixer transform generic font-family `system-ui`?
 263
 264 `system-ui` is technically not a prefix and the transformation is not future-proof. But you can use [postcss-font-family-system-ui](https://github.com/JLHwung/postcss-font-family-system-ui) to transform `system-ui` to a practical font-family list.
 265
 266 ## Usage
 267
 268 ### Gulp
 269
 270 In Gulp you can use [gulp-postcss] with `autoprefixer` npm package.
 271
 272 ```js
 273 gulp.task('autoprefixer', function () {
 274     var postcss      = require('gulp-postcss');
 275     var sourcemaps   = require('gulp-sourcemaps');
 276     var autoprefixer = require('autoprefixer');
 277
 278     return gulp.src('./src/*.css')
 279         .pipe(sourcemaps.init())
 280         .pipe(postcss([ autoprefixer() ]))
 281         .pipe(sourcemaps.write('.'))
 282         .pipe(gulp.dest('./dest'));
 283 });
 284 ```
 285
 286 With `gulp-postcss` you also can combine Autoprefixer
 287 with [other PostCSS plugins].
 288
 289 [other PostCSS plugins]: https://github.com/postcss/postcss#plugins
 290 [gulp-postcss]:          https://github.com/postcss/gulp-postcss
 291
 292 ### Webpack
 293
 294 In [webpack] you can use [postcss-loader] with `autoprefixer`
 295 and [other PostCSS plugins].
 296
 297 ```js
 298 module.exports = {
 299     module: {
 300         rules: [
 301             {
 302                 test: /\.css$/,
 303                 use: ["style-loader", "css-loader", "postcss-loader"]
 304             }
 305         ]
 306     }
 307 }
 308 ```
 309
 310 And create a `postcss.config.js` with:
 311
 312 ```js
 313 module.exports = {
 314   plugins: [
 315     require('autoprefixer')
 316   ]
 317 }
 318 ```
 319
 320 [other PostCSS plugins]: https://github.com/postcss/postcss#plugins
 321 [postcss-loader]:        https://github.com/postcss/postcss-loader
 322 [webpack]:               http://webpack.github.io/
 323
 324 ### Grunt
 325
 326 In Grunt you can use [grunt-postcss] with `autoprefixer` npm package.
 327
 328 ```js
 329 module.exports = function(grunt) {
 330     grunt.loadNpmTasks('grunt-postcss');
 331
 332     grunt.initConfig({
 333         postcss: {
 334             options: {
 335                 map: true,
 336                 processors: [
 337                     require('autoprefixer')
 338                 ]
 339             },
 340             dist: {
 341                 src: 'css/*.css'
 342             }
 343         }
 344     });
 345
 346     grunt.registerTask('default', ['postcss:dist']);
 347 };
 348 ```
 349
 350 With `grunt-postcss` you also can combine Autoprefixer
 351 with [other PostCSS plugins].
 352
 353 [other PostCSS plugins]: https://github.com/postcss/postcss#plugins
 354 [grunt-postcss]:         https://github.com/nDmitry/grunt-postcss
 355
 356 ### Other Build Tools:
 357
 358 * **Ruby on Rails**: [autoprefixer-rails]
 359 * **Neutrino**: [neutrino-middleware-postcss]
 360 * **Jekyll**: add `autoprefixer-rails` and `jekyll-assets` to `Gemfile`
 361 * **Brunch**: [postcss-brunch]
 362 * **Broccoli**: [broccoli-postcss]
 363 * **Middleman**: [middleman-autoprefixer]
 364 * **Mincer**: add `autoprefixer` npm package and enable it:
 365   `environment.enable('autoprefixer')`
 366
 367 [neutrino-middleware-postcss]: https://www.npmjs.com/package/neutrino-middleware-postcss
 368 [middleman-autoprefixer]:      https://github.com/middleman/middleman-autoprefixer
 369 [autoprefixer-rails]:          https://github.com/ai/autoprefixer-rails
 370 [broccoli-postcss]:            https://github.com/jeffjewiss/broccoli-postcss
 371 [postcss-brunch]:              https://github.com/iamvdo/postcss-brunch
 372
 373 ### Preprocessors
 374
 375 * **Less**: [less-plugin-autoprefix]
 376 * **Stylus**: [autoprefixer-stylus]
 377 * **Compass**: [autoprefixer-rails#compass]
 378
 379 [less-plugin-autoprefix]: https://github.com/less/less-plugin-autoprefix
 380 [autoprefixer-stylus]:    https://github.com/jenius/autoprefixer-stylus
 381 [autoprefixer-rails#compass]:     https://github.com/ai/autoprefixer-rails#compass
 382
 383 ### CSS-in-JS
 384
 385 There is [postcss-js] to use Autoprefixer in React Inline Styles, [Free Style],
 386 Radium and other CSS-in-JS solutions.
 387
 388 ```js
 389 let prefixer = postcssJs.sync([ autoprefixer ]);
 390 let style = prefixer({
 391     display: 'flex'
 392 });
 393 ```
 394
 395 [postcss-js]: https://github.com/postcss/postcss-js
 396 [Free Style]: https://github.com/blakeembrey/free-style
 397
 398 ### GUI Tools
 399
 400 * [CodeKit](https://codekitapp.com/help/autoprefixer/)
 401 * [Prepros](https://prepros.io)
 402
 403 ### CLI
 404
 405 You can use the [postcss-cli] to run Autoprefixer from CLI:
 406
 407 ```sh
 408 npm install postcss-cli autoprefixer
 409 npx postcss *.css --use autoprefixer -d build/
 410 ```
 411
 412 See `postcss -h` for help.
 413
 414 [postcss-cli]: https://github.com/postcss/postcss-cli
 415
 416 ### JavaScript
 417
 418 You can use Autoprefixer with [PostCSS] in your Node.js application
 419 or if you want to develop an Autoprefixer plugin for new environment.
 420
 421 ```js
 422 var autoprefixer = require('autoprefixer');
 423 var postcss      = require('postcss');
 424
 425 postcss([ autoprefixer ]).process(css).then(function (result) {
 426     result.warnings().forEach(function (warn) {
 427         console.warn(warn.toString());
 428     });
 429     console.log(result.css);
 430 });
 431 ```
 432
 433 There is also [standalone build] for the browser or as a non-Node.js runtime.
 434
 435 You can use [html-autoprefixer] to process HTML with inlined CSS.
 436
 437 [html-autoprefixer]: https://github.com/RebelMail/html-autoprefixer
 438 [standalone build]:  https://raw.github.com/ai/autoprefixer-rails/master/vendor/autoprefixer.js
 439 [PostCSS]:           https://github.com/postcss/postcss
 440
 441 ### Text Editors and IDE
 442
 443 Autoprefixer should be used in assets build tools. Text editor plugins are not
 444 a good solution, because prefixes decrease code readability and you will need
 445 to change value in all prefixed properties.
 446
 447 I recommend you to learn how to use build tools like [Gulp].
 448 They work much better and will open you a whole new world of useful plugins
 449 and automatization.
 450
 451 But, if you can’t move to a build tool, you can use text editor plugins:
 452
 453 * [Sublime Text](https://github.com/sindresorhus/sublime-autoprefixer)
 454 * [Brackets](https://github.com/mikaeljorhult/brackets-autoprefixer)
 455 * [Atom Editor](https://github.com/sindresorhus/atom-autoprefixer)
 456 * [Visual Studio](http://vswebessentials.com/)
 457
 458 [Gulp]:  http://gulpjs.com/
 459
 460 ## Warnings
 461
 462 Autoprefixer uses the [PostCSS warning API] to warn about really important problems
 463 in your CSS:
 464
 465 * Old direction syntax in gradients.
 466 * Old unprefixed `display: box` instead of `display: flex`
 467   by latest specification version.
 468
 469 You can get warnings from `result.warnings()`:
 470
 471 ```js
 472 result.warnings().forEach(function (warn) {
 473     console.warn(warn.toString());
 474 });
 475 ```
 476
 477 Every Autoprefixer runner should display this warnings.
 478
 479 [PostCSS warning API]: https://github.com/postcss/postcss/blob/master/docs/api.md#warning-class
 480
 481 ## Disabling
 482
 483 ### Prefixes
 484
 485 Autoprefixer was designed to have no interface – it just works.
 486 If you need some browser specific hack just write a prefixed property
 487 after the unprefixed one.
 488
 489 ```css
 490 a {
 491     transform: scale(0.5);
 492     -moz-transform: scale(0.6);
 493 }
 494 ```
 495
 496 If some prefixes were generated in a wrong way,
 497 please create an issue on GitHub.
 498
 499 ### Features
 500
 501 There are 4 plugin’s options to disable some Autoprefixer features.
 502
 503 * `supports: false` will disable `@supports` parameters prefixing.
 504 * `flexbox: false` will disable flexbox properties prefixing.
 505   Or `flexbox: "no-2009"` will add prefixes only for final and IE
 506   versions of specification.
 507 * `remove: false` will disable cleaning outdated prefixes.
 508
 509 You shoud set them to the plugin:
 510
 511 ```js
 512 autoprefixer({ grid: true });
 513 ```
 514
 515 ### Control Comments
 516
 517 If you do not need Autoprefixer in some part of your CSS,
 518 you can use control comments to disable Autoprefixer.
 519
 520 ```css
 521 a {
 522     transition: 1s; /* it will be prefixed */
 523 }
 524
 525 b {
 526     /* autoprefixer: off */
 527     transition: 1s; /* it will not be prefixed */
 528 }
 529 ```
 530
 531 Control comments disable Autoprefixer within the whole rule in which
 532 you place it. In the above example, Autoprefixer will be disabled
 533 in the entire `b` rule scope, not only after the comment.
 534
 535 You can also use comments recursively:
 536
 537 ```css
 538 /* autoprefixer: off */
 539 @supports (transition: all) {
 540     /* autoprefixer: on */
 541     a {
 542         /* autoprefixer: off */
 543     }
 544 }
 545 ```
 546
 547 In Sass/SCSS you can use all the disable options above, add an exclamation mark
 548 in the start of comment: `/*! autoprefixer: off */`.
 549
 550 ## Options
 551
 552 Function `autoprefixer(options)` returns new PostCSS plugin.
 553 See [PostCSS API] for plugin usage documentation.
 554
 555 ```js
 556 autoprefixer({ cascade: false })
 557 ```
 558
 559 There are 8 options:
 560
 561 * `browsers` (array): list of browsers query (like `last 2 versions`),
 562   which are supported in your project. We recommend to use `browserslist`
 563   config or `browserslist` key in `package.json`, rather than this option
 564   to share browsers with other tools. See [Browserslist docs] for available
 565   queries and default value.
 566 * `env` (string): environment for Browserslist.
 567 * `cascade` (boolean): should Autoprefixer use Visual Cascade,
 568   if CSS is uncompressed. Default: `true`
 569 * `add` (boolean): should Autoprefixer add prefixes. Default is `true`.
 570 * `remove` (boolean): should Autoprefixer [remove outdated] prefixes.
 571   Default is `true`.
 572 * `supports` (boolean): should Autoprefixer add prefixes for `@supports`
 573   parameters. Default is `true`.
 574 * `flexbox` (boolean|string): should Autoprefixer add prefixes for flexbox
 575   properties. With `"no-2009"` value Autoprefixer will add prefixes only
 576   for final and IE versions of specification. Default is `true`.
 577 * `grid` (boolean): should Autoprefixer add IE prefixes for Grid Layout
 578   properties. Default is `false`.
 579 * `stats` (object): custom [usage statistics] for `> 10% in my stats`
 580   browsers query.
 581
 582 Plugin object has `info()` method for debugging purpose.
 583
 584 You can use PostCSS processor to process several CSS files
 585 to increase performance.
 586
 587 [usage statistics]: https://github.com/ai/browserslist#custom-usage-data
 588 [PostCSS API]:      http://api.postcss.org
 589
 590 ## Debug
 591
 592 Run `npx autoprefixer-info --package autoprefixer` in your project directory to check
 593 which browsers are selected and which properties will be prefixed:
 594
 595 ```
 596 $ npx autoprefixer-info --package autoprefixer
 597 Browsers:
 598   Edge: 16
 599
 600 These browsers account for 0.04% of all users globally
 601
 602 At-Rules:
 603   @viewport: ms
 604
 605 Selectors:
 606   ::placeholder: ms
 607
 608 Properties:
 609   user-select: ms
 610   hyphens: ms
 611   appearance: webkit
 612   scroll-snap-type: ms
 613   scroll-snap-coordinate: ms
 614   scroll-snap-destination: ms
 615   scroll-snap-points-x: ms
 616   scroll-snap-points-y: ms
 617   flow-into: ms
 618   flow-from: ms
 619   region-fragment: ms
 620   text-spacing: ms
 621 ```
 622
 623 JS API is also available:
 624
 625 ```js
 626 var info = autoprefixer().info();
 627 console.log(info);
 628 ```