Dude, Where Is My CSS

Troubleshooting pages that are unstyled because the CSS fails to load.

By Bob Ray  |  September 15, 2022  |  4 min read
Dude, Where Is My CSS

Sometimes, when you view a page, say for a Snippet you’re working on, everything on the page runs down the left margin and is all in the same font and style. If the CSS is complicated, the result may be a page that looks really confused, with content missing, or text on top of other text. Usually, that means that your CSS is not being loaded by the browser. In this article, we’ll look at how to troubleshoot that situation.

View Source

The first thing to do is a "View Source" on the page (Ctrl-U in many browsers). This will show you the raw HTML code of the page. First, check to make sure that there is a <head> section at the top of the page. If you forgot to put a <head> section in your Template, the CSS won’t be recognized by the browser and the MODX code usually used to inject CSS won’t function. Sometimes this happens when the page Template accidentally gets switched to a blank Template.

Assuming that the <head> section at the top of the page is there, you should see a line something like this:

<link rel="stylesheet" href="/assets/components/yourComponent/css/cssfilename.css" type="text/css"/>

If there is no such line, then you need to look where your CSS is supposed to be injected (Snippet code, Template, Chunk, etc.). Whatever is supposed to be putting the line there isn’t doing its job.

If the line is there, click on it. In most browsers, this will load the CSS file as if it were a text file and show it to you. If nothing happens when you click on it, the URL of the file isn’t correct.

While you’re looking at the source of the page, check to make sure that the base href tag is there and is correct. If it’s not, your CSS probably won’t load correctly. Typically, the base href tag results from a tag like this in the <head> section of the Template:

<base href="[[!++site_url]]" />

Make sure the base href tag is there, is correct, and is a “short” tag like the one above. The tag needs to be uncached, so the inside of the tag should always begin with an exclamation point (!).

Some Common Problems

There are several reasons why the link to the CSS file won’t work. One is a permission problem with the CSS file itself. A second possibility is that the file is in a location that can’t be reached by URL. Generally, CSS files are placed under the MODX assets/ directory, where they are accessible by URL. If you have placed your CSS file under the core/ directory and that directory is protected from direct HTTP access by an .htaccess file, that’s why your CSS isn’t loading.

In my experience, the most common reason why CSS won’t load is confusing a path with a URL. If the link you see in the source is a physical path to the file, it won’t work. It has to be a URL, starting with https://. It doesn’t have to be a full URL, but sometimes making it one will correct a faulty URL.

If you are registering the CSS in code, this is typically the method you would use (note the use of the MODX_ASSETS_URL constant):

$cssPath = MODX_ASSETS_URL . 'components/mycomponent/css/cssfile.css';
$modx->regClientCSS($cssPath);

Because MODX_ASSETS_URL always ends with a slash, there should never be one at the beginning of the string that follows it. Otherwise, you’ll get a URL with a double slash in it that may not work.

MODX injects the code into the head section of the HTML code, which is why you need to make sure the page actually has a head section.

Less Common Problems

There’s a description of an uncommon cause of CSS not loading in this Forum post, though this should be fixed in the MODX setup code. Still, it’s an interesting read.

If you are placing the CSS in a Resource or in a Chunk placed in a Resource, or using a static Resource for the CSS, make sure the Resource has an empty Template. Otherwise, the browser will be trying to interpret the Template’s HTML code as CSS and may get very confused.

If the CSS in injected by a nested process, e.g., the Template contains a Chunk tag, the Chunk contains a Snippet tag, and the Snippet injects the CSS, the parsing order may be a factor. You can experiment with making the various tags cached or uncached, but it’s usually better to simply reduce the level of nesting by moving the part with the CSS code to a higher level. That will also speed up page loads.


Bob Ray is the author of the MODX: The Official Guide and dozens of MODX Extras including QuickEmail, NewsPublisher, SiteCheck, GoRevo, Personalize, EZfaq, MyComponent and many more. His website is Bob’s Guides. It not only includes a plethora of MODX tutorials but there are some really great bread recipes there, as well.