I've been using UnoCSS since its early days, and I'm quite amazed by its limitless flexibility. However, flexibility comes at a price and can lead you to misuse.

Note that this post focuses on UnoCSS using the default presets: Uno, Attributify and Tagify.

Ways to use UnoCSS

Before we start, let's review the ways we can use UnoCSS with the main presets:

• Classes <div class="dark:bg-gray-900">
• Attributes <div dark="bg-gray-900">
• Tags <dark-bg-gray-900>

Attributes

The attributify preset allows you to use HTML attributes instead of CSS classes as long as they are within the Unicode ranges supported by the specification.

However, that doesn't mean it strictly adheres to the HTML standard. For example, the following code:

<div dark="bg-gray-950">

It technically works in modern browsers, but if you run a validator you'll notice that "dark" is not a valid attribute in div tags.

Why is this the case? Custom attributes can conflict with future HTML attributes, causing unexpected behavior or rendering issues.

Using data-* attributes

So what do we do? data-* attributes allow us to extend HTML tags with any non-standard attribute we can think of. Of course, this also applies to the utilities generated by UnoCSS.

<div data-dark="bg-gray-950">

By default, the attributify preset doesn't support them, but you can enforce it by using this configuration:

presetAttributify({
  prefix: 'data-', // or 'data-un-'
  prefixedOnly: true,
})

Problem solved!

Tags

Tags have a similar problem. Custom HTML elements should follow these rules:

• The name of a custom element must contain a hyphen ("-").
• The name must start with a letter (a-z or A-Z).
• The name can contain lowercase letters (a-z), uppercase letters (A-Z), digits (0-9), hyphens ("-"), and must not contain any whitespace or special characters.

Hyphens

Most utilities like <text-red-300> work fine, but prefixed tags like dark: or print: may be problematic, as colons are not supported. In fact, tagify won't work at all!

Let's say we have this example:

<dark:text-red-300>

We should replace the colon with a hyphen:

<dark-text-red-300>

Prefixes

Many utilities, such as <flex> or <hidden>, do not contain dashes because they consist of single words. Splitting them, for example into , wouldn't make sense.

Instead, we can use a namespace prefix:

presetTagify({
  prefix: 'un-'
})

This means that you can write utilities like <un-flex> or <un-dark-flex> and be at ease since no new elements containing hyphens will be added to the HTML specification.