README.md
1# Autoprefixer [![Cult Of Martians][cult-img]][cult]
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
8from [Can I Use]. It is [recommended] by Google and used in Twitter and Alibaba.
9
10Write your CSS rules without vendor prefixes (in fact, forget about them
11entirely):
12
13```css
14::placeholder {
15 color: gray;
16}
17
18.image {
19 background-image: url(image@1x.png);
20}
21@media (min-resolution: 2dppx) {
22 .image {
23 background-image: url(image@2x.png);
24 }
25}
26```
27
28Autoprefixer will use the data based on current browser popularity and property
29support to apply prefixes for you. You can try the [interactive demo]
30of Autoprefixer.
31
32```css
33::-webkit-input-placeholder {
34 color: gray;
35}
36::-moz-placeholder {
37 color: gray;
38}
39:-ms-input-placeholder {
40 color: gray;
41}
42::-ms-input-placeholder {
43 color: gray;
44}
45::placeholder {
46 color: gray;
47}
48
49.image {
50 background-image: url(image@1x.png);
51}
52@media (-webkit-min-device-pixel-ratio: 2),
53 (-o-min-device-pixel-ratio: 2/1),
54 (min-resolution: 2dppx) {
55 .image {
56 background-image: url(image@2x.png);
57 }
58}
59```
60
61Twitter account for news and releases: [@autoprefixer].
62
63<a href="https://evilmartians.com/?utm_source=autoprefixer">
64<img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg" alt="Sponsored by Evil Martians" width="236" height="54">
65</a>
66
67[interactive demo]: https://autoprefixer.github.io/
68[@autoprefixer]: https://twitter.com/autoprefixer
69[recommended]: https://developers.google.com/web/tools/setup/setup-buildtools#dont_trip_up_with_vendor_prefixes
70[Can I Use]: https://caniuse.com/
71[cult-img]: http://cultofmartians.com/assets/badges/badge.svg
72[PostCSS]: https://github.com/postcss/postcss
73[cult]: http://cultofmartians.com/tasks/autoprefixer-grid.html
74
75
76## Contents
77
78* [Contents](#contents)
79* [Browsers](#browsers)
80* [FAQ](#faq)
81 * [Does Autoprefixer polyfill Grid Layout for IE?](#does-autoprefixer-polyfill-grid-layout-for-ie)
82 * [Does it add polyfills?](#does-it-add-polyfills)
83 * [Why doesn’t Autoprefixer add prefixes to `border-radius`?](#why-doesnt-autoprefixer-add-prefixes-to-border-radius)
84 * [Why does Autoprefixer use unprefixed properties in `@-webkit-keyframes`?](#why-does-autoprefixer-use-unprefixed-properties-in--webkit-keyframes)
85 * [How to work with legacy `-webkit-` only code?](#how-to-work-with-legacy--webkit--only-code)
86 * [Does Autoprefixer add `-epub-` prefix?](#does-autoprefixer-add--epub--prefix)
87 * [Why doesn’t Autoprefixer transform generic font-family `system-ui`?](#why-doesnt-autoprefixer-transform-generic-font-family-system-ui)
88* [Usage](#usage)
89 * [Gulp](#gulp)
90 * [Webpack](#webpack)
91 * [CSS-in-JS](#css-in-js)
92 * [CLI](#cli)
93 * [Other Build Tools](#other-build-tools)
94 * [Preprocessors](#preprocessors)
95 * [GUI Tools](#gui-tools)
96 * [JavaScript](#javascript)
97 * [Text Editors and IDE](#text-editors-and-ide)
98* [Warnings](#warnings)
99* [Disabling](#disabling)
100 * [Prefixes](#prefixes)
101 * [Features](#features)
102 * [Control Comments](#control-comments)
103* [Options](#options)
104* [Environment Variables](#environment-variables)
105 * [Using environment variables to support CSS Grid prefixes in Create React App](#using-environment-variables-to-support-css-grid-prefixes-in-create-react-app)
106* [Grid Autoplacement support in IE](#grid-autoplacement-support-in-ie)
107 * [Beware of enabling autoplacement in old projects](#beware-of-enabling-autoplacement-in-old-projects)
108 * [Autoplacement limitations](#autoplacement-limitations)
109 * [Both columns and rows must be defined](#both-columns-and-rows-must-be-defined)
110 * [Repeat auto-fit and auto-fill are not supported](#repeat-auto-fit-and-auto-fill-are-not-supported)
111 * [No manual cell placement or column/row spans allowed inside an autoplacement grid](#no-manual-cell-placement-or-columnrow-spans-allowed-inside-an-autoplacement-grid)
112 * [Do not create `::before` and `::after` pseudo elements](#do-not-create-before-and-after-pseudo-elements)
113 * [When changing the `grid gap` value, columns and rows must be re-declared](#when-changing-the-grid-gap-value-columns-and-rows-must-be-re-declared)
114* [Debug](#debug)
115* [Security Contact](#security-contact)
116* [For Enterprise](#for-enterprise)
117
118## Browsers
119
120Autoprefixer uses [Browserslist], so you can specify the browsers
121you want to target in your project with queries like `> 5%`
122(see [Best Practices]).
123
124The best way to provide browsers is a `.browserslistrc` file in your project
125root, or by adding a `browserslist` key to your `package.json`.
126
127We recommend the use of these options over passing options to Autoprefixer so
128that the config can be shared with other tools such as [babel-preset-env] and
129[Stylelint].
130
131See [Browserslist docs] for queries, browser names, config format, and defaults.
132
133[Browserslist docs]: https://github.com/browserslist/browserslist#queries
134[babel-preset-env]: https://github.com/babel/babel/tree/master/packages/babel-preset-env
135[Best Practices]: https://github.com/browserslist/browserslist#best-practices
136[Browserslist]: https://github.com/browserslist/browserslist
137[Stylelint]: https://stylelint.io/
138
139
140## FAQ
141
142### Does Autoprefixer polyfill Grid Layout for IE?
143
144Autoprefixer can be used to translate modern CSS Grid syntax into IE 10
145and IE 11 syntax, but this polyfill will not work in 100% of cases.
146This is why it is disabled by default.
147
148First, you need to enable Grid prefixes by using either the `grid: "autoplace"`
149option or the `/* autoprefixer grid: autoplace */` control comment.
150Also you can use environment variable to enable Grid:
151`AUTOPREFIXER_GRID=autoplace npm build`.
152
153Second, you need to test every fix with Grid in IE. It is not an enable and
154forget feature, but it is still very useful.
155Financial Times and Yandex use it in production.
156
157Third, there is only very limited auto placement support. Read the
158[Grid Autoplacement support in IE](#grid-autoplacement-support-in-ie) section
159for more details.
160
161Fourth, if you are not using the autoplacement feature, the best way
162to use Autoprefixer is by using `grid-template` or `grid-template-areas`.
163
164```css
165.page {
166 display: grid;
167 grid-gap: 33px;
168 grid-template:
169 "head head head" 1fr
170 "nav main main" minmax(100px, 1fr)
171 "nav foot foot" 2fr /
172 1fr 100px 1fr;
173}
174.page__head {
175 grid-area: head;
176}
177.page__nav {
178 grid-area: nav;
179}
180.page__main {
181 grid-area: main;
182}
183.page__footer {
184 grid-area: foot;
185}
186```
187
188See also:
189
190* [The guide about Grids in IE and Autoprefixer].
191* [`postcss-gap-properties`] to use new `gap` property
192 instead of old `grid-gap`.
193* [`postcss-grid-kiss`] has alternate “everything in one property” syntax,
194 which makes using Autoprefixer’s Grid translations safer.
195
196[The guide about Grids in IE and Autoprefixer]: https://css-tricks.com/css-grid-in-ie-css-grid-and-the-new-autoprefixer/
197[`postcss-gap-properties`]: https://github.com/jonathantneal/postcss-gap-properties
198[`postcss-grid-kiss`]: https://github.com/sylvainpolletvillard/postcss-grid-kiss
199
200
201### Does it add polyfills?
202
203No. Autoprefixer only adds prefixes.
204
205Most new CSS features will require client side JavaScript to handle a new
206behavior correctly.
207
208Depending on what you consider to be a “polyfill”, you can take a look at some
209other tools and libraries. If you are just looking for syntax sugar,
210you might take a look at:
211
212- [postcss-preset-env] is a plugins preset with polyfills and Autoprefixer
213 to write future CSS today.
214- [Oldie], a PostCSS plugin that handles some IE hacks (opacity, rgba, etc).
215- [postcss-flexbugs-fixes], a PostCSS plugin to fix flexbox issues.
216
217[postcss-flexbugs-fixes]: https://github.com/luisrudge/postcss-flexbugs-fixes
218[postcss-preset-env]: https://github.com/jonathantneal/postcss-preset-env
219[Oldie]: https://github.com/jonathantneal/oldie
220
221
222### Why doesn’t Autoprefixer add prefixes to `border-radius`?
223
224Developers are often surprised by how few prefixes are required today.
225If Autoprefixer doesn’t add prefixes to your CSS, check if they’re still
226required on [Can I Use].
227
228[Can I Use]: https://caniuse.com/
229
230
231### Why does Autoprefixer use unprefixed properties in `@-webkit-keyframes`?
232
233Browser teams can remove some prefixes before others, so we try to use all
234combinations of prefixed/unprefixed values.
235
236
237### How to work with legacy `-webkit-` only code?
238
239Autoprefixer needs unprefixed property to add prefixes. So if you only
240wrote `-webkit-gradient` without W3C’s `gradient`,
241Autoprefixer will not add other prefixes.
242
243But [PostCSS] has plugins to convert CSS to unprefixed state.
244Use [postcss-unprefix] before Autoprefixer.
245
246[postcss-unprefix]: https://github.com/gucong3000/postcss-unprefix
247
248
249### Does Autoprefixer add `-epub-` prefix?
250
251No, Autoprefixer works only with browsers prefixes from Can I Use.
252But you can use [postcss-epub] for prefixing ePub3 properties.
253
254[postcss-epub]: https://github.com/Rycochet/postcss-epub
255
256
257### Why doesn’t Autoprefixer transform generic font-family `system-ui`?
258
259`system-ui` is technically not a prefix and the transformation is not
260future-proof. You can use [postcss-font-family-system-ui] to transform
261`system-ui` to a practical font-family list.
262
263[postcss-font-family-system-ui]: https://github.com/JLHwung/postcss-font-family-system-ui
264
265
266## Usage
267
268### Gulp
269
270In Gulp you can use [gulp-postcss] with `autoprefixer` npm package.
271
272```js
273gulp.task('autoprefixer', () => {
274 const autoprefixer = require('autoprefixer')
275 const sourcemaps = require('gulp-sourcemaps')
276 const postcss = require('gulp-postcss')
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
286With `gulp-postcss` you also can combine Autoprefixer
287with [other PostCSS plugins].
288
289[gulp-postcss]: https://github.com/postcss/gulp-postcss
290[other PostCSS plugins]: https://github.com/postcss/postcss#plugins
291
292
293### Webpack
294
295In [webpack] you can use [postcss-loader] with `autoprefixer`
296and [other PostCSS plugins].
297
298```js
299module.exports = {
300 module: {
301 rules: [
302 {
303 test: /\.css$/,
304 use: ["style-loader", "css-loader", "postcss-loader"]
305 }
306 ]
307 }
308}
309```
310
311And create a `postcss.config.js` with:
312
313```js
314module.exports = {
315 plugins: [
316 require('autoprefixer')
317 ]
318}
319```
320
321[other PostCSS plugins]: https://github.com/postcss/postcss#plugins
322[postcss-loader]: https://github.com/postcss/postcss-loader
323[webpack]: https://webpack.js.org/
324
325
326### CSS-in-JS
327
328The best way to use PostCSS with CSS-in-JS is [`astroturf`].
329Add its loader to your `webpack.config.js`:
330
331```js
332module.exports = {
333 module: {
334 rules: [
335 {
336 test: /\.css$/,
337 use: ['style-loader', 'postcss-loader'],
338 },
339 {
340 test: /\.jsx?$/,
341 use: ['babel-loader', 'astroturf/loader'],
342 }
343 ]
344 }
345}
346```
347
348Then create `postcss.config.js`:
349
350```js
351module.exports = {
352 plugins: [
353 require('autoprefixer')
354 ]
355}
356```
357
358[`astroturf`]: https://github.com/4Catalyzer/astroturf
359
360
361### CLI
362
363You can use the [postcss-cli] to run Autoprefixer from CLI:
364
365```sh
366npm install postcss-cli autoprefixer
367npx postcss *.css --use autoprefixer -d build/
368```
369
370See `postcss -h` for help.
371
372[postcss-cli]: https://github.com/postcss/postcss-cli
373
374
375### Other Build Tools
376
377* **Grunt:** [grunt-postcss]
378* **Ruby on Rails**: [autoprefixer-rails]
379* **Neutrino**: [neutrino-middleware-postcss]
380* **Jekyll**: add `autoprefixer-rails` and `jekyll-assets` to `Gemfile`
381* **Brunch**: [postcss-brunch]
382* **Broccoli**: [broccoli-postcss]
383* **Middleman**: [middleman-autoprefixer]
384* **Mincer**: add `autoprefixer` npm package and enable it:
385 `environment.enable('autoprefixer')`
386
387[neutrino-middleware-postcss]: https://www.npmjs.com/package/neutrino-middleware-postcss
388[middleman-autoprefixer]: https://github.com/middleman/middleman-autoprefixer
389[autoprefixer-rails]: https://github.com/ai/autoprefixer-rails
390[broccoli-postcss]: https://github.com/jeffjewiss/broccoli-postcss
391[postcss-brunch]: https://github.com/iamvdo/postcss-brunch
392[grunt-postcss]: https://github.com/nDmitry/grunt-postcss
393
394
395#### Preprocessors
396
397* **Less**: [less-plugin-autoprefix]
398* **Stylus**: [autoprefixer-stylus]
399* **Compass**: [autoprefixer-rails#compass]
400
401[less-plugin-autoprefix]: https://github.com/less/less-plugin-autoprefix
402[autoprefixer-stylus]: https://github.com/jenius/autoprefixer-stylus
403[autoprefixer-rails#compass]: https://github.com/ai/autoprefixer-rails#compass
404
405
406#### GUI Tools
407
408* [CodeKit](https://codekitapp.com/help/autoprefixer/)
409* [Prepros](https://prepros.io)
410
411
412### JavaScript
413
414You can use Autoprefixer with [PostCSS] in your Node.js application
415or if you want to develop an Autoprefixer plugin for a new environment.
416
417```js
418const autoprefixer = require('autoprefixer')
419const postcss = require('postcss')
420
421postcss([ autoprefixer ]).process(css).then(result => {
422 result.warnings().forEach(warn => {
423 console.warn(warn.toString())
424 })
425 console.log(result.css)
426})
427```
428
429There is also a [standalone build] for the browser or for a non-Node.js runtime.
430
431You can use [html-autoprefixer] to process HTML with inlined CSS.
432
433[html-autoprefixer]: https://github.com/RebelMail/html-autoprefixer
434[standalone build]: https://raw.github.com/ai/autoprefixer-rails/master/vendor/autoprefixer.js
435[PostCSS]: https://github.com/postcss/postcss
436
437
438### Text Editors and IDE
439
440Autoprefixer should be used in assets build tools. Text editor plugins are not
441a good solution, because prefixes decrease code readability and you will need
442to change values in all prefixed properties.
443
444I recommend you to learn how to use build tools like [Parcel].
445They work much better and will open you a whole new world of useful plugins
446and automation.
447
448If you can’t move to a build tool, you can use text editor plugins:
449
450* [Visual Studio Code](https://github.com/mrmlnc/vscode-autoprefixer)
451* [Atom Editor](https://github.com/sindresorhus/atom-autoprefixer)
452* [Sublime Text](https://github.com/sindresorhus/sublime-autoprefixer)
453* [Brackets](https://github.com/mikaeljorhult/brackets-autoprefixer)
454
455[Parcel]: https://parceljs.org/
456
457
458## Warnings
459
460Autoprefixer uses the [PostCSS warning API] to warn about really important
461problems in your CSS:
462
463* Old direction syntax in gradients.
464* Old unprefixed `display: box` instead of `display: flex`
465 by latest specification version.
466
467You can get warnings from `result.warnings()`:
468
469```js
470result.warnings().forEach(warn => {
471 console.warn(warn.toString())
472})
473```
474
475Every Autoprefixer runner should display these warnings.
476
477[PostCSS warning API]: http://api.postcss.org/Warning.html
478
479
480## Disabling
481
482### Prefixes
483
484Autoprefixer was designed to have no interface – it just works.
485If you need some browser specific hack just write a prefixed property
486after the unprefixed one.
487
488```css
489a {
490 transform: scale(0.5);
491 -moz-transform: scale(0.6);
492}
493```
494
495If some prefixes were generated incorrectly, please create an [issue on GitHub].
496
497[issue on GitHub]: https://github.com/postcss/autoprefixer/issues
498
499
500### Features
501
502You can use these plugin options to control some of Autoprefixer’s features.
503
504* `grid: "autoplace"` will enable `-ms-` prefixes for Grid Layout including some
505 [limited autoplacement support](#grid-autoplacement-support-in-ie).
506* `supports: false` will disable `@supports` parameters prefixing.
507* `flexbox: false` will disable flexbox properties prefixing.
508 Or `flexbox: "no-2009"` will add prefixes only for final and IE
509 versions of specification.
510* `remove: false` will disable cleaning outdated prefixes.
511
512You should set them inside the plugin like so:
513
514```js
515autoprefixer({ grid: 'autoplace' })
516```
517
518
519### Control Comments
520
521If you do not need Autoprefixer in some part of your CSS,
522you can use control comments to disable Autoprefixer.
523
524```css
525.a {
526 transition: 1s; /* will be prefixed */
527}
528
529.b {
530 /* autoprefixer: off */
531 transition: 1s; /* will not be prefixed */
532}
533
534.c {
535 /* autoprefixer: ignore next */
536 transition: 1s; /* will not be prefixed */
537 mask: url(image.png); /* will be prefixed */
538}
539```
540
541There are three types of control comments:
542
543* `/* autoprefixer: (on|off) */`: enable/disable all Autoprefixer translations for the
544 whole block both *before* and *after* the comment.
545* `/* autoprefixer: ignore next */`: disable Autoprefixer only for the next property
546 or next rule selector or at-rule parameters (but not rule/at‑rule body).
547* `/* autoprefixer grid: (autoplace|no-autoplace|off) */`: control how Autoprefixer handles
548 grid translations for the whole block:
549 * `autoplace`: enable grid translations with autoplacement support.
550 * `no-autoplace`: enable grid translations with autoplacement
551 support *disabled* (alias for deprecated value `on`).
552 * `off`: disable all grid translations.
553
554You can also use comments recursively:
555
556```css
557/* autoprefixer: off */
558@supports (transition: all) {
559 /* autoprefixer: on */
560 a {
561 /* autoprefixer: off */
562 }
563}
564```
565
566Note that comments that disable the whole block should not be featured in the same
567block twice:
568
569```css
570/* How not to use block level control comments */
571
572.do-not-do-this {
573 /* autoprefixer: off */
574 transition: 1s;
575 /* autoprefixer: on */
576 transform: rotate(20deg);
577}
578```
579
580
581## Options
582
583Function `autoprefixer(options)` returns a new PostCSS plugin.
584See [PostCSS API] for plugin usage documentation.
585
586```js
587autoprefixer({ cascade: false })
588```
589
590Available options are:
591
592* `env` (string): environment for Browserslist.
593* `cascade` (boolean): should Autoprefixer use Visual Cascade,
594 if CSS is uncompressed. Default: `true`
595* `add` (boolean): should Autoprefixer add prefixes. Default is `true`.
596* `remove` (boolean): should Autoprefixer [remove outdated] prefixes.
597 Default is `true`.
598* `supports` (boolean): should Autoprefixer add prefixes for `@supports`
599 parameters. Default is `true`.
600* `flexbox` (boolean|string): should Autoprefixer add prefixes for flexbox
601 properties. With `"no-2009"` value Autoprefixer will add prefixes only
602 for final and IE 10 versions of specification. Default is `true`.
603* `grid` (false|`"autoplace"`|`"no-autoplace"`): should Autoprefixer
604 add IE 10-11 prefixes for Grid Layout properties?
605 * `false` (default): prevent Autoprefixer from outputting
606 CSS Grid translations.
607 * `"autoplace"`: enable Autoprefixer grid translations
608 and *include* autoplacement support. You can also use
609 `/* autoprefixer grid: autoplace */` in your CSS.
610 * `"no-autoplace"`: enable Autoprefixer grid translations
611 but *exclude* autoplacement support. You can also use
612 `/* autoprefixer grid: no-autoplace */` in your CSS.
613 (alias for the deprecated `true` value)
614* `stats` (object): custom [usage statistics] for `> 10% in my stats`
615 browsers query.
616* `overrideBrowserslist` (array): list of queries for target browsers.
617 Try to not use it. The best practice is to use `.browserslistrc` config
618 or `browserslist` key in `package.json` to share target browsers
619 with Babel, ESLint and Stylelint. See [Browserslist docs]
620 for available queries and default value.
621* `ignoreUnknownVersions` (boolean): do not raise error on unknown browser
622 version in Browserslist config. Default is `false`.
623
624Plugin object has `info()` method for debugging purpose.
625
626You can use PostCSS processor to process several CSS files
627to increase performance.
628
629[usage statistics]: https://github.com/browserslist/browserslist#custom-usage-data
630[PostCSS API]: http://api.postcss.org
631
632## Environment Variables
633
634* `AUTOPREFIXER_GRID`: (`autoplace`|`no-autoplace`) should Autoprefixer
635 add IE 10-11 prefixes for Grid Layout properties?
636 * `autoplace`: enable Autoprefixer grid translations
637 and *include* autoplacement support.
638 * `no-autoplace`: enable Autoprefixer grid translations
639 but *exclude* autoplacement support.
640
641Environment variables are useful, when you want to change Autoprefixer options but don't have access to config files.
642[Create React App] is a good example of this.
643
644[Create React App]: (https://reactjs.org/docs/create-a-new-react-app.html#create-react-app)
645
646### Using environment variables to support CSS Grid prefixes in Create React App
647
6481. Install the latest version of Autoprefixer and [cross-env](https://www.npmjs.com/package/cross-env):
649
650```
651npm install autoprefixer@latest cross-env --save-dev
652```
653
6542. Under `"browserslist"` > `"development"` in the package.json file, add `"last 1 ie version"`
655
656```
657"browserslist": {
658 "production": [
659 ">0.2%",
660 "not dead",
661 "not op_mini all"
662 ],
663 "development": [
664 "last 1 chrome version",
665 "last 1 firefox version",
666 "last 1 safari version",
667 "last 1 ie version"
668 ]
669}
670```
671
6723. Update `"scripts"` in the package.json file to the following:
673
674```
675"scripts": {
676 "start": "cross-env AUTOPREFIXER_GRID=autoplace react-scripts start",
677 "build": "cross-env AUTOPREFIXER_GRID=autoplace react-scripts build",
678 "test": "cross-env AUTOPREFIXER_GRID=autoplace react-scripts test",
679 "eject": "react-scripts eject"
680},
681```
682
683Replace `autoplace` with `no-autoplace` in the above example if you prefer to disable Autoprefixer Grid autoplacement support.
684
685Now when you run `npm start` you will see CSS Grid prefixes automatically being applied to your output CSS.
686
687See also [Browserslist environment variables] for more examples on how to use environment variables in your project.
688
689[Browserslist environment variables]: https://github.com/browserslist/browserslist#environment-variables
690
691## Grid Autoplacement support in IE
692
693If the `grid` option is set to `"autoplace"`, limited autoplacement support is added to Autoprefixers grid translations. You can also use
694the `/* autoprefixer grid: autoplace */` control comment or
695`AUTOPREFIXER_GRID=autoplace npm build` environment variable.
696
697Autoprefixer will only autoplace grid cells if both `grid-template-rows`
698and `grid-template-columns` has been set. If `grid-template`
699or `grid-template-areas` has been set, Autoprefixer will use area based
700cell placement instead.
701
702Autoprefixer supports autoplacement by using `nth-child` CSS selectors.
703It creates [number of columns] x [number of rows] `nth-child` selectors.
704For this reason Autoplacement is only supported within the explicit grid.
705
706```css
707/* Input CSS */
708
709/* autoprefixer grid: autoplace */
710
711.autoplacement-example {
712 display: grid;
713 grid-template-columns: 1fr 1fr;
714 grid-template-rows: auto auto;
715 grid-gap: 20px;
716}
717```
718
719```css
720/* Output CSS */
721
722/* autoprefixer grid: autoplace */
723
724.autoplacement-example {
725 display: -ms-grid;
726 display: grid;
727 -ms-grid-columns: 1fr 20px 1fr;
728 grid-template-columns: 1fr 1fr;
729 -ms-grid-rows: auto 20px auto;
730 grid-template-rows: auto auto;
731 grid-gap: 20px;
732}
733
734.autoplacement-example > *:nth-child(1) {
735 -ms-grid-row: 1;
736 -ms-grid-column: 1;
737}
738
739.autoplacement-example > *:nth-child(2) {
740 -ms-grid-row: 1;
741 -ms-grid-column: 3;
742}
743
744.autoplacement-example > *:nth-child(3) {
745 -ms-grid-row: 3;
746 -ms-grid-column: 1;
747}
748
749.autoplacement-example > *:nth-child(4) {
750 -ms-grid-row: 3;
751 -ms-grid-column: 3;
752}
753```
754
755### Beware of enabling autoplacement in old projects
756
757Be careful about enabling autoplacement in any already established projects that have
758previously not used Autoprefixer's grid autoplacement feature before.
759
760If this was your html:
761
762```html
763<div class="grid">
764 <div class="grid-cell"></div>
765</div>
766```
767
768The following CSS will not work as expected with the autoplacement feature enabled:
769
770```css
771/* Unsafe CSS when Autoplacement is enabled */
772
773.grid-cell {
774 grid-column: 2;
775 grid-row: 2;
776}
777
778.grid {
779 display: grid;
780 grid-template-columns: repeat(3, 1fr);
781 grid-template-rows: repeat(3, 1fr);
782}
783```
784
785Swapping the rules around will not fix the issue either:
786
787```css
788/* Also unsafe to use this CSS */
789
790.grid {
791 display: grid;
792 grid-template-columns: repeat(3, 1fr);
793 grid-template-rows: repeat(3, 1fr);
794}
795
796.grid-cell {
797 grid-column: 2;
798 grid-row: 2;
799}
800```
801
802One way to deal with this issue is to disable autoplacement in the
803grid-declaration rule:
804
805```css
806/* Disable autoplacement to fix the issue */
807
808.grid {
809 /* autoprefixer grid: no-autoplace */
810 display: grid;
811 grid-template-columns: repeat(3, 1fr);
812 grid-template-rows: repeat(3, 1fr);
813}
814
815.grid-cell {
816 grid-column: 2;
817 grid-row: 2;
818}
819```
820
821The absolute best way to integrate autoplacement into already existing projects
822though is to leave autoplacement turned off by default and then use a control
823comment to enable it when needed. This method is far less likely to cause
824something on the site to break.
825
826```css
827/* Disable autoplacement by default in old projects */
828/* autoprefixer grid: no-autoplace */
829
830/* Old code will function the same way it always has */
831.old-grid {
832 display: grid;
833 grid-template-columns: repeat(3, 1fr);
834 grid-template-rows: repeat(3, 1fr);
835}
836.old-grid-cell {
837 grid-column: 2;
838 grid-row: 2;
839}
840
841/* Enable autoplacement when you want to use it in new code */
842.new-autoplace-friendly-grid {
843 /* autoprefixer grid: autoplace */
844 display: grid;
845 grid-template-columns: repeat(3, 1fr);
846 grid-template-rows: repeat(3, auto);
847}
848```
849
850Note that the `grid: "no-autoplace"` setting and the
851`/* autoprefixer grid: no-autoplace */` control comment share identical
852functionality to the `grid: true` setting and the `/* autoprefixer grid: on */`
853control comment. There is no need to refactor old code to use `no-autoplace`
854in place of the old `true` and `on` statements.
855
856### Autoplacement limitations
857
858#### Both columns and rows must be defined
859
860Autoplacement only works inside the explicit grid. The columns and rows need to be defined
861so that Autoprefixer knows how many `nth-child` selectors to generate.
862
863```css
864.not-allowed {
865 display: grid;
866 grid-template-columns: repeat(3, 1fr);
867}
868
869.is-allowed {
870 display: grid;
871 grid-template-columns: repeat(3, 1fr);
872 grid-template-rows: repeat(10, auto);
873}
874```
875
876#### Repeat auto-fit and auto-fill are not supported
877
878The `repeat(auto-fit, ...)` and `repeat(auto-fill, ...)` grid functionality relies on
879knowledge from the browser about screen dimensions and the number of available grid
880items for it to work properly. Autoprefixer does not have access to this information
881so unfortunately this little snippet will _never_ be IE friendly.
882
883```css
884.grid {
885 /* This will never be IE friendly */
886 grid-template-columns: repeat(auto-fit, min-max(200px, 1fr))
887}
888```
889
890#### No manual cell placement or column/row spans allowed inside an autoplacement grid
891
892Elements must not be manually placed or given column/row spans inside
893an autoplacement grid. Only the most basic of autoplacement grids are supported.
894Grid cells can still be placed manually outside the the explicit grid though.
895Support for manually placing individual grid cells inside an explicit
896autoplacement grid is planned for a future release.
897
898```css
899.autoplacement-grid {
900 display: grid;
901 grid-template-columns: repeat(3, 1fr);
902 grid-template-rows: repeat(3, auto);
903}
904
905/* Grid cells placed inside the explicit grid
906 will break the layout in IE */
907.not-permitted-grid-cell {
908 grid-column: 1;
909 grid-row: 1;
910}
911
912/* Grid cells placed outside the
913 explicit grid will work in IE */
914.permitted-grid-cell {
915 grid-column: 1 / span 2;
916 grid-row: 4;
917}
918```
919
920If manual cell placement is required, we recommend using `grid-template` or
921`grid-template-areas` instead:
922
923```css
924.page {
925 display: grid;
926 grid-gap: 30px;
927 grid-template:
928 "head head"
929 "nav main" minmax(100px, 1fr)
930 "foot foot" /
931 200px 1fr;
932}
933.page__head {
934 grid-area: head;
935}
936.page__nav {
937 grid-area: nav;
938}
939.page__main {
940 grid-area: main;
941}
942.page__footer {
943 grid-area: foot;
944}
945```
946
947#### Do not create `::before` and `::after` pseudo elements
948
949Let's say you have this HTML:
950
951```html
952<div class="grid">
953 <div class="grid-cell"></div>
954</div>
955```
956
957And you write this CSS:
958
959```css
960.grid {
961 display: grid;
962 grid-template-columns: 1fr 1fr;
963 grid-template-rows: auto;
964}
965
966.grid::before {
967 content: 'before';
968}
969
970.grid::after {
971 content: 'after';
972}
973```
974
975This will be the output:
976
977```css
978.grid {
979 display: -ms-grid;
980 display: grid;
981 -ms-grid-columns: 1fr 1fr;
982 grid-template-columns: 1fr 1fr;
983 -ms-grid-rows: auto;
984 grid-template-rows: auto;
985}
986
987.grid > *:nth-child(1) {
988 -ms-grid-row: 1;
989 -ms-grid-column: 1;
990}
991
992
993.grid > *:nth-child(2) {
994 -ms-grid-row: 1;
995 -ms-grid-column: 2;
996}
997
998.grid::before {
999 content: 'before';
1000}
1001
1002.grid::after {
1003 content: 'after';
1004}
1005```
1006
1007IE will place `.grid-cell`, `::before` and `::after` in row 1 column 1.
1008Modern browsers on the other hand will place `::before` in row 1 column 1,
1009`.grid-cell` in row 1 column 2, and `::after` in row 2 column 1.
1010
1011See this [Code Pen](https://codepen.io/daniel-tonon/pen/gBymVw) to see a visualization
1012of the issue. View the Code Pen in both a modern browser and IE to see the difference.
1013
1014Note that you can still create `::before` and `::after` elements as long as you manually
1015place them outside the explicit grid.
1016
1017#### When changing the `grid gap` value, columns and rows must be re-declared
1018
1019If you wish to change the size of a `grid-gap`, you will need to redeclare the grid columns and rows.
1020
1021```css
1022.grid {
1023 display: grid;
1024 grid-template-columns: 1fr 1fr;
1025 grid-template-rows: auto;
1026 grid-gap: 50px;
1027}
1028
1029/* This will *NOT* work in IE */
1030@media (max-width: 600px) {
1031 .grid {
1032 grid-gap: 20px;
1033 }
1034}
1035
1036/* This will *NOT* work in IE */
1037.grid.small-gap {
1038 grid-gap: 20px;
1039}
1040```
1041
1042```css
1043.grid {
1044 display: grid;
1045 grid-template-columns: 1fr 1fr;
1046 grid-template-rows: auto;
1047 grid-gap: 50px;
1048}
1049
1050/* This *WILL* work in IE */
1051@media (max-width: 600px) {
1052 .grid {
1053 grid-template-columns: 1fr 1fr;
1054 grid-template-rows: auto;
1055 grid-gap: 20px;
1056 }
1057}
1058
1059/* This *WILL* work in IE */
1060.grid.small-gap {
1061 grid-template-columns: 1fr 1fr;
1062 grid-template-rows: auto;
1063 grid-gap: 20px;
1064}
1065```
1066
1067## Debug
1068
1069Run `npx autoprefixer --info` in your project directory to check
1070which browsers are selected and which properties will be prefixed:
1071
1072```
1073$ npx autoprefixer --info
1074Browsers:
1075 Edge: 16
1076
1077These browsers account for 0.26% of all users globally
1078
1079At-Rules:
1080 @viewport: ms
1081
1082Selectors:
1083 ::placeholder: ms
1084
1085Properties:
1086 appearance: webkit
1087 flow-from: ms
1088 flow-into: ms
1089 hyphens: ms
1090 overscroll-behavior: ms
1091 region-fragment: ms
1092 scroll-snap-coordinate: ms
1093 scroll-snap-destination: ms
1094 scroll-snap-points-x: ms
1095 scroll-snap-points-y: ms
1096 scroll-snap-type: ms
1097 text-size-adjust: ms
1098 text-spacing: ms
1099 user-select: ms
1100```
1101
1102JS API is also available:
1103
1104```js
1105console.log(autoprefixer().info())
1106```
1107
1108## Security Contact
1109
1110To report a security vulnerability, please use the [Tidelift security contact].
1111Tidelift will coordinate the fix and disclosure.
1112
1113[Tidelift security contact]: https://tidelift.com/security
1114
1115## For Enterprise
1116
1117Available as part of the Tidelift Subscription.
1118
1119The maintainers of `autoprefixer` and thousands of other packages are working
1120with Tidelift to deliver commercial support and maintenance for the open source
1121dependencies you use to build your applications. Save time, reduce risk,
1122and improve code health, while paying the maintainers of the exact dependencies
1123you use. [Learn more.](https://tidelift.com/subscription/pkg/npm-autoprefixer?utm_source=npm-autoprefixer&utm_medium=referral&utm_campaign=enterprise&utm_term=repo)
1124