Troubleshooting

Common issues solved

This document outlines some of the "gotchas" that Users developing Components for Elements have run into.

Dynamic PHP Code and Tailwind Classes Generation

When using PHP to generate or include HTML dynamically, you might notice that some Tailwind CSS classes are missing, causing the intended styling not to be applied. This issue arises from how Tailwind’s Just-In-Time (JIT) engine builds the CSS.

How It Works

Tailwind’s JIT engine will only compile the CSS classes it finds in your component's template files at build or preview time. This approach minimises the final CSS file size by including only the styles needed for the current content. However, if your PHP code generates additional Tailwind classes at runtime (for example, by inserting them into the page after it’s built), those classes will not be recognized during the build process, and their corresponding styles will be omitted.

Workaround

If you know in advance which Tailwind classes your PHP code will generate dynamically, you can ensure they are included in the final CSS by listing them in your template. A common method is to include them in an HTML comment in one of your template files. For example:

<!--
  The following classes are dynamically generated:
  bg-red-500, text-center, w-1/2, h-full.
-->

This comment is scanned by Elements when building Tailwind, so even though the classes are not directly rendered in the HTML, their styles will be generated and available to the HTML code generated by your PHP code.

By using this technique, you ensure that all required Tailwind classes are compiled, keeping your dynamic content styled correctly regardless of when the classes are added.

You can learn more about this here: Just-in-Time friendly style variants in Tailwind CSS UI components, and in this thread on the Elements Forum.