Why arbitrary values exist in Tailwind - Why It Works This Way

Overview - Why arbitrary values exist

What is it?

Arbitrary values in Tailwind CSS let you use custom styles that are not part of the default set. Instead of being limited to predefined sizes, colors, or spacing, you can write your own values directly in your class names. This gives you more control and flexibility when designing your webpage. It works by wrapping your custom value in square brackets inside the class name.

Why it matters

Without arbitrary values, you would be stuck using only the fixed options Tailwind provides. This can make your designs look repetitive or force you to write extra CSS. Arbitrary values solve this by letting you quickly add unique styles without leaving your HTML. This saves time and keeps your code clean and consistent.

Where it fits

Before learning arbitrary values, you should understand basic Tailwind utility classes and how Tailwind's design system works. After mastering arbitrary values, you can explore advanced customization like plugins, theming, and responsive design with custom breakpoints.

Mental Model

Core Idea

Arbitrary values let you break free from preset styles by writing exact custom values inside Tailwind class names.

Think of it like...

It's like having a toolbox with fixed-size screws but suddenly being able to create screws of any size you want on the spot, without needing a new toolbox.

Tailwind Classes
┌───────────────────────────────┐
│ Predefined class:             │
│   p-4 (padding: 1rem)         │
│ Arbitrary value class:        │
│   p-[18px] (padding: 18px)    │
└───────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Understanding Tailwind Utility Classes

Concept: Learn what Tailwind utility classes are and how they apply styles.

Tailwind CSS uses small class names like 'p-4' or 'text-red-500' to add styles directly in HTML. Each class corresponds to a specific CSS property and value, like padding or color. These classes come from a fixed set defined in Tailwind's configuration.

Result

You can quickly style elements by adding these classes without writing CSS files.

Knowing how utility classes map to CSS helps you see why fixed sets can sometimes limit design flexibility.

2

Foundation

Limits of Predefined Tailwind Values

Concept: Recognize the constraints of using only Tailwind's default values.

Tailwind offers a set of spacing, colors, and sizes like 'p-4' or 'text-blue-600'. But sometimes you need a size or color not in this set, like padding of 18px or a custom shade. Without arbitrary values, you'd have to write custom CSS or extend Tailwind's config.

Result

You understand why fixed utility classes might not cover every design need.

Seeing these limits motivates the need for a way to add custom values easily.

3

Intermediate

Using Arbitrary Values in Tailwind

🤔Before reading on: Do you think you can write any CSS value directly inside a Tailwind class? Commit to yes or no.

Concept: Learn how to write custom values inside square brackets in Tailwind class names.

Tailwind lets you write classes like 'w-[350px]' or 'bg-[#123abc]' where the value inside brackets is any valid CSS value. This overrides the default scale and applies exactly what you specify. For example, 'mt-[7.5rem]' sets margin-top to 7.5rem.

Result

You can apply precise styles without changing Tailwind's config or writing CSS.

Understanding this syntax unlocks Tailwind's full flexibility without losing utility-first benefits.

4

Intermediate

Syntax Rules for Arbitrary Values

🤔Before reading on: Do you think spaces are allowed inside arbitrary value brackets? Commit to yes or no.

Concept: Learn the correct syntax and limitations for writing arbitrary values.

Arbitrary values must be wrapped in square brackets with no spaces inside. For example, 'text-[20px]' is valid, but 'text-[ 20px ]' is not. You can use units like px, rem, %, hex colors, rgb, and even calc(). Some characters like '/' or '#' need escaping or special handling.

Result

You write valid arbitrary classes that Tailwind can parse and apply.

Knowing syntax rules prevents errors and helps you write clean, working classes.

5

Intermediate

Combining Arbitrary Values with Variants

🤔Before reading on: Can you use arbitrary values with responsive or hover variants like 'md:' or 'hover:'? Commit to yes or no.

Concept: Understand how arbitrary values work with Tailwind's variant prefixes.

You can prefix arbitrary value classes with variants like 'hover:bg-[red]' or 'md:w-[400px]'. This applies the custom value only on hover or at medium screen sizes. This keeps your design responsive and interactive while using custom styles.

Result

You create flexible, custom-styled components that respond to user actions and screen sizes.

Knowing this lets you combine Tailwind's power with custom values seamlessly.

6

Advanced

Performance and Build Considerations

🤔Before reading on: Do you think using many arbitrary values can affect Tailwind's build size or performance? Commit to yes or no.

Concept: Learn how arbitrary values impact Tailwind's build process and CSS size.

Tailwind generates CSS only for classes it finds in your files. Arbitrary values create unique CSS rules for each value, which can increase CSS size if overused. Also, some build tools might struggle with complex arbitrary values. It's best to use them thoughtfully and prefer config extensions for repeated values.

Result

You balance flexibility with performance and maintainability.

Understanding build impact helps you avoid bloated CSS and slow builds in real projects.

7

Expert

Internal Parsing and Future-proofing

🤔Before reading on: Do you think Tailwind's arbitrary value syntax is stable and will support all CSS features forever? Commit to yes or no.

Concept: Explore how Tailwind parses arbitrary values and the design choices behind it.

Tailwind uses a parser that scans your HTML/JSX for class names and extracts arbitrary values inside brackets. It validates and converts them to CSS. This design balances flexibility with safety, but some complex CSS features might not be supported yet. Tailwind evolves to support new CSS specs, so staying updated is important.

Result

You understand the limits and evolution of arbitrary values in Tailwind.

Knowing the parsing mechanism prepares you for future changes and helps debug tricky issues.

Under the Hood

Tailwind scans your project files for class names during build time. When it finds a class with square brackets, it extracts the value inside and generates a CSS rule with that exact value. This happens before the CSS is sent to the browser, so the browser only sees standard CSS. The parser ensures the value is valid CSS syntax to avoid errors.

Why designed this way?

Tailwind was designed to be utility-first and fast. Predefining every possible value would be impossible and bloated. Arbitrary values let users add any style without config changes or extra CSS files. This design keeps Tailwind flexible and lightweight, avoiding the need for custom CSS while supporting unique designs.

Project Files
  │
  ▼
Class Name Scanner
  │
  ├─ Detects fixed classes (e.g., p-4)
  └─ Detects arbitrary classes (e.g., p-[18px])
        │
        ▼
  CSS Generator
        │
        └─ Creates CSS rules with exact values
              │
              ▼
         Final CSS Output
              │
              ▼
          Browser renders styles

Myth Busters - 4 Common Misconceptions

Quick: Do you think arbitrary values can contain spaces inside the brackets? Commit to yes or no.

Common Belief: You can write arbitrary values with spaces inside brackets like 'p-[10 px]'.

Reality: Spaces inside arbitrary value brackets are not allowed and will cause errors or be ignored.

Why it matters: Using spaces breaks the class parsing, so your styles won't apply and debugging becomes harder.

Quick: Do you think arbitrary values are always better than extending Tailwind config? Commit to yes or no.

Common Belief: Arbitrary values are the best way to add any custom style, no config needed.

Reality: While convenient, overusing arbitrary values can bloat CSS and hurt performance; extending config is better for repeated or theme-related values.

Why it matters: Ignoring config extensions leads to messy, large CSS files and harder maintenance.

Quick: Do you think arbitrary values can be used with all CSS properties in Tailwind? Commit to yes or no.

Common Belief: You can use arbitrary values with any CSS property in Tailwind classes.

Reality: Only properties supported by Tailwind's parser and syntax can use arbitrary values; some complex or shorthand properties may not work.

Why it matters: Trying unsupported properties causes silent failures or unexpected styles.

Quick: Do you think arbitrary values are a new feature that replaces all Tailwind defaults? Commit to yes or no.

Common Belief: Arbitrary values replace the need for any predefined Tailwind classes.

Reality: Arbitrary values complement, not replace, the default utility classes which are optimized and easier to maintain.

Why it matters: Ignoring defaults leads to inconsistent design and more complex code.

Expert Zone

1

Arbitrary values bypass Tailwind's design tokens, so they don't respond to theme changes like dark mode or color palettes automatically.

2

Using arbitrary values with dynamic content (like in frameworks) requires careful escaping to avoid build errors or security issues.

3

Tailwind's parser has limits on certain characters inside brackets, so sometimes you need to escape or encode values, which can be tricky.

When NOT to use

Avoid arbitrary values when you need consistent theming, repeated styles, or want to leverage Tailwind's design system fully. Instead, extend the Tailwind config with custom colors, spacing, or plugins. Also, avoid arbitrary values for complex CSS that Tailwind doesn't support well; write custom CSS or use CSS-in-JS instead.

Production Patterns

In production, developers use arbitrary values sparingly for one-off tweaks or unique components. Most styles come from the config for consistency. Arbitrary values are common in rapid prototyping or when integrating third-party designs. Teams often combine config extensions with arbitrary values for balance.

Connections

CSS Variables

Builds-on

Knowing arbitrary values helps understand how CSS variables can be used dynamically in Tailwind for even more flexible styling.

Design Tokens

Opposite

Arbitrary values let you break free from design tokens, but understanding tokens helps maintain consistent design systems.

Software Configuration Management

Similar pattern

Just like config files manage software settings, Tailwind config manages design scales; arbitrary values are like on-the-fly overrides, showing a common pattern of balancing defaults with custom overrides.

Common Pitfalls

#1 Writing arbitrary values with spaces inside brackets.

Wrong approach:

p-[10 px]

Correct approach:

p-[10px]

Root cause:

Misunderstanding that spaces are allowed inside arbitrary value syntax.

#2 Overusing arbitrary values for repeated styles.

Wrong approach:

Correct approach:

Extend Tailwind config with a custom font size and use that class repeatedly.

Root cause:

Not realizing config extensions improve maintainability and reduce CSS size.

#3 Using arbitrary values with unsupported CSS properties.

Wrong approach:

border-[solid 1px red]

Correct approach:

Use separate Tailwind classes like 'border border-red-500 border-solid'.

Root cause:

Assuming arbitrary values work for all CSS shorthand properties.

Key Takeaways

Arbitrary values let you write exact CSS styles inside Tailwind class names for unmatched flexibility.

They solve the problem of limited predefined utility classes without needing extra CSS files or config changes.

Correct syntax and thoughtful use are essential to avoid errors and maintain performance.

Arbitrary values complement Tailwind's design system but should not replace config extensions for repeated styles.

Understanding how Tailwind parses and generates CSS from arbitrary values helps you use them effectively and debug issues.