Using EQCSS with CSS Preprocessors

EQCSS is a non-standard extension of CSS syntax that is interpreted at runtime. There are a number of ways you can use EQCSS, and it may also be possible to work with EQCSS syntax if you are writing CSS using a preprocessor like SASS, Less, Stylus, or PostCSS.

The 4 ways that the EQCSS.js plugin can read styles are: from a <style> tag, from an external CSS stylesheet loaded via <link>, from a <script type=text/eqcss> tag, or loaded from an external EQCSS file loaded via <script src="" type=text/eqcss>. Typically in a normal frontend build process, only 1 of these ways EQCSS can be loaded (via external CSS stylesheet) would be preprocessed, so before I explain the ways you can work around EQCSS syntax using different preprocessors I'll explain the other 3 ways of loading EQCSS.

Loading EQCSS via inline <style> tag

Once the EQCSS.js plugin has been added to a page it will scan the document for all <style> tags and parse them for EQCSS syntax. This is a very common way I have added element queries to pages as I will usually be writing the bulk of my styles in external CSS stylesheets. I'm slightly hesitant to add EQCSS to an external CSS stylesheet because it's not immediately obvious to other developers that any stylesheet that includes EQCSS syntax requires EQCSS.js on the page in order to load those rules.

Loading EQCSS via <script type=text/eqcss>

This was the original way the EQCSS.js plugin would read styles. When people ask what EQCSS will do if future versions of CSS conflict with any of our syntax - the most obvious answer is that putting your EQCSS code in a custom script type ensures that the browser never sees your EQCSS as CSS, never tries to parse it as CSS, and you can be 100% sure only EQCSS.js is looking at that code. This ensures forward-compatibility forever even when the direction forward is uncertain.

Loading EQCSS via external EQCSS file using <script src="" type=text/eqcss>

One added benefit to storing your EQCSS syntax in its own file is that you can set your editor to apply CSS syntax highlighting to your .eqcss files while maintaining a total separation of your CSS styles from your EQCSS styles (if that is desirable). The added bonus to this method is that any developer looking in a /styles/ folder and seeing .eqcss files is an obvious hint that a plugin will be required to read these files as they are very apparently not regular CSS files.

Loading EQCSS via external CSS file using <link>

This is the second easiest method for loading EQCSS. Anywhere you can write regular CSS you can include EQCSS as well, and as long as EQCSS.js is present on the page at the time the stylesheet loads it will parse and interpret the styles. This method also allows you to include EQCSS in CSS stylesheets output by preprocessors like SASS, Less, Stylus, PostCSS, and others. Here are a few tips & tricks to help navigate around EQCSS's custom syntax while using these tools.

EQCSS & SASS

• the meta-selectors $this, $root, $parent, $prev, and $next are also aliased with eq_ in addition to $, allowing you to write the same selectors as eq_this, eq_root, eq_parent, eq_prev, and eq_next anywhere. This should remove the conflict between SASS and $

• Github user @thejase has written a SASS mixin to generate @element queries which should further help SASS users

EQCSS & Less

• the meta-selectors $this, $root, $parent, $prev, and $next are also aliased with eq_ in addition to $, allowing you to write the same selectors as eq_this, eq_root, eq_parent, eq_prev, and eq_next anywhere. This should remove the conflict between Less and $

EQCSS & Stylus

• the meta-selectors $this, $root, $parent, $prev, and $next are also aliased with eq_ in addition to $, allowing you to write the same selectors as eq_this, eq_root, eq_parent, eq_prev, and eq_next anywhere. This should remove the conflict between Stylus and $

• Github user @findborg comments about using EQCSS with Stylus:

Getting stylus to play nice was a little bit of a trick. It kept changing the word "and" to "&&". It took me two nights to find the problem. I am sure you know the feeling. I fixed the problem by escaping the word like this \a\n\d. Now I can use stylus vars in eqcss and ready to rock and roll!

EQCSS & PostCSS

More info needed (let me know, or edit this if you have experience using these two together)

Troubleshooting

Currently EQCSS syntax is unspecified, but we are working to get a spec drafted so it can be proposed. Many tool authors may be waiting until a spec is at least proposed before adding any support for the syntax from their end - so if you find yourself trying to use EQCSS with your tools now and it's not working inside the tools, it may be a lot simpler to include your EQCSS syntax using one of the other methods listed above (.eqcss file, script tag, inline style tag) to exclude it from your preprocessing build process entirely!