There are no tracking or monitoring cookies on this site. There are only cookies used for documentation examples related to cookies.
Close

Processing...
This may take a few seconds.

Installation

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-5-0.min.js"></script>

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 inline 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.

Inline Active CSS

You can run Active CSS inline in your HTML page in addition to, or instead of, config files. As of 2.4.0 inline Active CSS should work dynamically like CSS.

If you are only using inline 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 and load it as config automatically.

To write inline 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 inline Active CSS event!";
}
</style>

The rules of the config are exactly the same in style tags as they are in config files.

Please note: Do not mix CSS with Active CSS, unless the CSS is inside event declarations.

Using style tags as the method of inline Active CSS gives us consistency with CSS and the chance for some possible syntax highlighting, if somewhat limited, from text editors.

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

If you have commands that would normally get run in a body:init or body:preInit event, obviously these will not work if you are dynamically loading inline Active CSS as Active CSS has already initialised. Instead, where you would normally put the "body:preInit" event use the new "inlineTag:loaded" event.

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 styling commands in Active CSS, but only inside events.

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 server can't handle it easily just use ".txt".

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 inline 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.

    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 inline 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

    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
    });