Installation

However you use ACSS in production, you only need one file from the GitHub repo - the ACSS minified core file. All the other files are used to build the ACSS minified core file. You are not expected to do that. You only need the latest minified version of the core. You don't need to fork the repo to use ACSS.

As a simple plug-in

First of all, download the latest stable release of Active CSS.

Insert the script tag below somewhere on your web page, such as the head tag, or at the end of the body tag.

<script src="/activecss/activecss-2-13-0.min.js"></script>

Note for running locally without a webserver:

If you are running a webserver, it is fine to use the "/" at the beginning of the src="/..." part. This will make it an absolute path, and the activecss directory will be found on the public web root directory.

If you are not running a webserver, and you are opening up an HTML file on your local computer, you use a relative path - not an absolute path - like this:

<script src="activecss/activecss-2-13-0.min.js"></script>

Note that there is no / at the beginning of the src attribute.

The activecss directory would be in the same directory on your computer as the html file that you are loading into your browser.

Last resort for running locally:

If you are having trouble with loading the core file because you are having difficulty understanding the computer words "absolute" and "relative" and just want to have a play around with ACSS, just do this:

<script src="activecss-2-13-0.min.js"></script>

... and on your computer put the activecss-2-13-0.min.js file in the same directory as your html file. The core file does not need to be in its own directory, like "activecss/", to work. There are no security implications in doing this. Putting files into directories for a web site is not essential, but it does help to organize if you have a lot of files.

Using NPM

After setting up the dependency for the npm version of the core, this is the import code you need to run the production version of Active CSS:

import ActiveCSS from "active-css";

(If you are running the dev version of the core, use from "active-css-dev" and if core-dev version, then from "active-css-core-dev".)

After that, type in the "Initialising Active CSS" steps below to initialise Active CSS. But if you are only using embedded Active CSS (ie. Active CSS inside a style tag) then you don't have to type in the "Initialising Active CSS" steps.

Check out the downloads page for the locations of the latest npm versions.

Embedded Active CSS

You can run Active CSS embedded in your HTML page in addition to, or instead of, config files.

This technique will load and unload your embedded events automatically if importing or overwriting HTML, just like it would if it was regular CSS. It can be useful if you want to apply some events to elements on only one page, and you don't want to clutter up your main config script. You can place your one-off code into an embedded style tag inside the HTML block, which loads your events. When that HTML block gets deleted later on, your events will automatically unload.

If you are only using embedded Active CSS, you can skip the "Initialising Active CSS" section on this page - you don't need to do anything other than include the core file in the script tag. The core will recognise that Active CSS is on the page, look for any embedded ACSS style tags, and load them as config automatically.

To write embedded ACSS, set up a style tag with a type of "text/acss". You can have multiple style tags on the page.

For example:

<style type="text/acss">
body:click {
    alert: "Hello, I am an Active CSS event in an embedded tag!";
}
</style>

Please note that regular CSS rules placed inside of ACSS style tags will only start having an effect once ACSS has finished loading. So only include CSS rules inside ACSS config if it is not needed for styling when the page is first loaded. Allowing CSS rules in ACSS config was introduced in version 2.8.0.

Dynamically loaded embedded Active CSS - replacement for body:init event

If you have commands that would normally get run in a body:init or body:preInit event, and you need these in your embedded ACSS config, these will not work if you are dynamically loading embedded Active CSS because Active CSS has already initialized and the initialization events have already run. Instead, where you would normally put the "body:preInit" event use the "embedded:loaded" event. This is most applicable when building an SPA, where body initialization events only run when the page is first entered.

Setting up your config file

All Active CSS code gets its own file, called a config file.

You cannot put Active CSS code into a CSS file.

You can use CSS rules in Active CSS, but unless you want flicker then the CSS should only for dynamic styling purposes.

To reiterate, Active CSS code needs to be in its own file. Do not attempt to put Active CSS code into any CSS file, as it will not work.

Follow these next instructions to set up an empty Active CSS config file. You can change file names or directory names to suit your setup.

Open up an empty text file and save it somewhere, calling it "config.acss". It doesn't have to be ".acss", so if you discover that your server cannot handle the ".acss" extension just use ".txt". It doesn't matter to the core - it just needs to be able to load and read a text file..

Your Active CSS config goes into this config file. Whenever you see the words "config file" on this website, it means the file where you put your Active CSS code. It is definitely not recommended that you use the ".css" extension for Active CSS files, as technically they are not CSS files and things will break.

Initialising Active CSS

If you are only using embedded Active CSS and there is no dedicated config file, you can skip this section altogether - you don't need to do anything other than include the core file in the script tag.

When you put the Active CSS plugin onto your page, nothing will happen until you initialize it. When you initialize it, you need to tell it where to find your config file(s).

Active CSS should be initialized only when the page has fully loaded. This can only be done with JavaScript, as Active CSS needs to know where to find your config files.

Initialize Active CSS by calling the "init" function with the path and filename you have set up for your config file. This code below can go into any JavaScript file you already currently load, or you can set up a new JavaScript file to contain something like this:

document.addEventListener('DOMContentLoaded', function(e) {
    ActiveCSS.init({
        configLocation: '/activecss/config.txt'
    });
});

The above code waits until the page is fully drawn, and then runs Active CSS.

Make sure you are loading this JavaScript Active CSS initialization code after the script tag which loads the Active CSS core. Otherwise you will get a "Active CSS is undefined" error.

You will probably want the page to be fully drawn before activating Active CSS, as Active CSS performs some initialization steps and ideally the page should be fully drawn before these occur, hence the use of the DOMContentLoaded event above. See the "Initialization events" section under "Events" in the docs to see which events run at initialization.

You will also have to use DOMContentLoaded if you use "defer" in the script tag because the core needs to load before initialising can begin.

That's it. No further JavaScript is required to get started. You can now edit your config file and start writing your commands.

On initialization, Active CSS reads the config file once at start up to put it into memory, and then refers to your config dynamically when events happen on the page.

Using multiple config files

Follow the exact syntax below to use multiple config files. You can name the config files whatever you want. For example, you could do this:

document.addEventListener('DOMContentLoaded', function(e) {
    ActiveCSS.init({
        configLocation: '/activecss/config.txt, /activecss/conditionals.txt, /activecss/components.txt',
    });
});

Lazy loading config

There is a way to delay loading config that you don't need right away in order to speed up initial page starting. So Active CSS will initialize, wait for a second, and then load the rest. You generally won't need this unless you are using massive amounts of config. This method is not used on this documentation website as it seems to be fast enough anyway - and there is a lot of config on this site.

You can lazy load multiple config files, by comma delimiting the files as shown in the previous section.

To implement lazy loading, follow this syntax:

ActiveCSS.init({
    configLocation: '/activecss-config/config.txt',
    lazyConfig: '/activecss-config/lazied-config.txt',
});

The only thing to bear in mind about this is that if you are lazy-loading "draw" events on anything pre-rendered from the server, the drawing of the element has already happened by the time the lazy-loading starts, so the "draw" event won't run - the draw event will only work on future draws, after the config has loaded. Ie. any "draw" events that happen when the page is first drawn will not work if you lazy-load them, as those events have already occurred by the time the lazy-loading has completed.

Important note: If you are building an SPA, do not lazy-load any @pages declarations. Don't worry yet if that doesn't make sense - building an SPA comes later. If you are at that point, you should know that ACSS needs your page navigation available right away in order to store the first page's information correctly so that browser navigation can work as expected. If the page details are not there at the point of page load, it is assumed that the freshly loaded page is not part of the SPA. So be sure not to have any @pages declarations in lazy-loaded config.

Dynamically loading config files

To load up files whenever you want, see the action command load-config.

"View source" is not showing the config file

When you "view source" on your browser page, you will not see your config file listed as loaded unless you are writing embedded Active CSS. This is perfectly normal. The reason is that Active CSS config files are not loaded by the browser, they are loaded by Active CSS internally.

To check if your config is actually loading at all, you can inspect your browser console log and look at the ajax calls occurring. Alternatively, you can view your events or config from the DevTools extension, if you have that. If you see the config in there and it looks correct, then it has loaded. There are also a couple of initialization debug options you can use if you don't have the extension or want to delve deeper into the core processing results to see what is going on. See the Debugging section for more on that.

Passive events, and using prevent-default outside of config

Note: Don't read this if you are just starting out, or you are not very familiar with JavaScript, as you'll only get confused. It's an advanced scenario.

This is a bit technical and to do with event listeners. Passive events are a relatively new thing to do with rendering performance on the browser. It is native technology. Generally you won't need to worry about this, as the most optimum setup is handled internally automatically by Active CSS, but if you are trying to run prevent-default outside of the config in your external JavaScript you need this information.

Active CSS will establish if you are using prevent-default in your config for a specific event, and if it is not being used then the default setting for the "passive" option - when adding the event listener - will be set to true.

Reference: https://developers.google.com/web/tools/lighthouse/audits/passive-event-listeners

Loading new config will override the event listeners passive state if you introduce a prevent-default later on. So as long as you are using the Active CSS prevent-default command, all will be fine.

This is great, but what if you are using preventDefault not in the config but inside a function within Active CSS or external to Active CSS? The preventDefault will not work - there will be an illegal invocation error as you cannot preventDefault an event that is set up as a passive event. The immediate solution for this is to put an option in your config to say you don't want any events to be set to true - set "passiveEvents" to false. The default is true. This is a niche scenario and hence a drastic workaround but this is the only option at the moment. The graphical implications of slowness aren't that massive with this solution, but flag it up if you need a more tailored solution and it will be added in.

ActiveCSS.init({
    configLocation: '/activecss-config/config.txt',
    passiveEvents: false
});