Arbitrary values without a build step

#Try it

This page loads the script, so these boxes are styled by classes that are not in the stylesheet. Switch the preview to dark to see the dark: value apply.

<div class="grid grid-cols-[repeat(auto-fit,minmax(9rem,1fr))] gap-3">
  <div class="rounded-[14px] bg-[#0ea5e9] p-4 text-white font-[650]">...</div>
  <div class="rounded-[14px] bg-[oklch(0.72_0.16_150)] p-4">...</div>
  <div class="rounded-[14px] border-[3px] border-[#a855f7] dark:text-[#e9d5ff]">...</div>
</div>

#The syntax

#One prefix, two meanings

A few prefixes write a color or a size depending on the value, exactly like their static classes do (border-2 and border-primary). The value decides:

When a value is ambiguous, for example a custom property, add a hint before a colon: color:, length:, size:, position:, image:, number:, weight: or family-name:. So bg-[length:200px_100px] is a background size and border-(color:--edge) is a border color.

#Variants

Every prefix of the static classes works on arbitrary values, on every family, and they can be stacked. The order on the page is the same as in the stylesheet: plain values first, then states, then breakpoints from small to large, then container and media queries.

<div class="hover:bg-[#0369a1] md:w-[37rem] dark:text-[#eee]">
<div class="@container"><div class="grid @md:grid-cols-[1fr_2fr]">...</div></div>
<nav class="print:hidden rtl:mr-[3px]">
<p class="md:hover:underline-offset-[6px]">
<span class="before:content-['#'] before:mr-[.25em]">

These are the rules the last line writes:

.before\:content-\[\'\#\'\]::before{content:'#'}
@media (min-width: 768px){.md\:hover\:underline-offset-\[6px\]:hover{text-underline-offset:6px}}

Besides the static variants, arbitrary values also take before:, after:, placeholder:, selection:, marker:, file:, backdrop:, first-line: and first-letter: (pseudo elements are always written last), plus visited:, checked:, invalid:, required:, empty:, target:, open:, group-focus: and peer-focus:.

The dark: prefix uses the same rule as the rest of Monsoon: the nearest themed ancestor wins, at any depth.

#Runtime or compiled

Both modes use the same parser, from src/arbitrary/, so a class means exactly the same thing in development and in production.

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/monsooncss@0.2.0">
<script src="https://cdn.jsdelivr.net/npm/monsooncss@0.2.0/dist/monsoon-arbitrary.js" defer></script>

npx monsooncss purge "src/**/*.{html,jsx,vue,php}" -o public/monsoon.css

monsooncss purge: scanned 42 files
  kept 512 of 16351 utility rules
  compiled 18 arbitrary value classes

#Safety

Class attributes can come from user content, so the parser only accepts values that cannot leave their declaration. A class is ignored, and nothing is written, when its value:

• contains ;, {, }, @, !, < or >, so it cannot end a declaration, open a rule or an at-rule, add !important or close a <style> element;
• contains a backslash other than \_, so nothing can hide behind a CSS escape;
• contains a comment, a control character, expression( or javascript:;
• has unbalanced brackets, parentheses or quotes;
• is longer than 300 characters, or uses an unknown prefix or variant.

Selectors are escaped with the same rules as CSS.escape, and property names of arbitrary properties must be plain lowercase names or custom properties. The test suite feeds the parser a list of injection attempts and checks that none of them produces a rule.

bg-[red;color:blue]          ignored: ";"
w-[1px}]                     ignored: "}" and unbalanced
content-['</style>']         ignored: "<" and ">"
bg-[\7d]                     ignored: escape
bg-[red_!important]          ignored: "!"

#Every family

Each prefix maps to the same properties as the static classes with that prefix. The table is generated from the parser, so it is always complete.

#Bare color names

Every palette hue also works without a step: bg-red, text-blue, border-emerald, ring-violet, from-sky. These are static classes in the stylesheet, no script needed. They use step 500 in light mode and step 400 in dark mode, and follow the nearest themed ancestor like every semantic color.

#Frequently asked questions