Fallback solution to using native CSS variables and applying & updating them dynamically.
We had a use case where we needed to allow admin users to choose and update their site's theme colors on demand. We couldn't find an acceptable solution except for native CSS variables / custom properties, which in its current state is only supported by some of the newest browsers. So we created this plugin to offer a fallback solution to be able to use native CSS variables in any browser on the :root element. Once browser support for native CSS variables is up to par you can simply remove this plugin from your build process.
Once you have have your task properly configured, the grunt build will create a separate stylesheet for you which contains only CSS rules which contain custom properties (with variables). You can then apply a fallback solution to browsers that don't support native CSS variables by doing the following:
- Detect browser support of native CSS variables, for example:
var supportsCssVars = function() { var TEST_KEY = '--test-variable'; var TEST_VALUE = 'test value'; document.body.style.setProperty(TEST_KEY, TEST_VALUE); var _nativeSupport = document.body.style.getPropertyValue(TEST_KEY) === TEST_VALUE; if (_nativeSupport) { document.body.style.removeProperty(TEST_KEY); } return _nativeSupport; };
- For browsers that DO support native variables, inject your new CSS variables at any time just like you would inject any styles.
- For browsers that do NOT support native variables:
- Use an
ajax
call to grab the stylesheet created by this plugin - Replace the variables (i.e.,
var(--your-variable)
) with your new values. For example:for (var prop in styles) { var re = new RegExp('var\\(\\-\\-' + prop + '\\)', 'g'); // replaces `var(--variable-name)` styles = styles.replace(re, styles[prop]); }
- Inject the updated styles into the DOM.
- Use an
If you haven't used Grunt before, be sure to check out:
- Getting Started with Grunt
- Sample Gruntfile
Once grunt
is installed, install this plugin with this command:
npm install grunt-css-variables --save-dev
Then enable it in your Gruntfile with this line:
grunt.loadNpmTasks('grunt-css-variables');
In your project's Gruntfile, add a section named css_variables
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
css_variables: {
options: {
// Task-specific options go here.
},
your_target: {
// Target-specific file lists and/or options go here.
},
},
});
Type: String
Default value: '{{filename}}--variables.css'
Filename of the stylesheet which is to contain the custom CSS properties from your original source. Note: {{filename}}
will be replaced by the source filename.
Type: Boolean
Default value: true
Whether to modify the original source styles and include the :root
variable value as a fallback to the native CSS custom property value (which can then later by modified dynamically).
Type: Boolean
Default value: true
Whether to minify the final css file(s).
In this example, the default options are used to do something with whatever. So if the testing
file has the content Testing
and the 123
file had the content 1 2 3
, the generated result would be Testing, 1 2 3.
grunt.initConfig({
css_variables: {
options: {},
files: {
'dest/default': ['src/test.css', 'src/test2.css'],
},
},
});
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
- 0.0.1 First release