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.

Practice

1. Why do arbitrary values exist in Tailwind CSS?

easy

A. To allow using any custom CSS value beyond default Tailwind options

B. To restrict styling only to predefined Tailwind classes

C. To automatically generate animations

D. To replace JavaScript functionality

Solution

1. Step 1: Understand Tailwind's default options

   Tailwind provides many predefined classes but cannot cover every possible CSS value.

2. Step 2: Purpose of arbitrary values

   Arbitrary values let you write any CSS value inside square brackets to customize styles beyond defaults.

3. Final Answer:

   To allow using any custom CSS value beyond default Tailwind options -> Option A

4. Quick Check:

   Arbitrary values = custom CSS values [OK]

Hint: Think: Custom styles beyond presets use arbitrary values [OK]

Common Mistakes:

• Thinking arbitrary values limit styling
• Confusing arbitrary values with animations
• Believing arbitrary values replace JavaScript

2. Which of the following is the correct syntax to set a custom width of 450 pixels using Tailwind's arbitrary values?

easy

A. width-450

B. w-[450px]

C. w-450px

D. width-[450]

Solution

1. Step 1: Recall Tailwind arbitrary value syntax

   Arbitrary values use square brackets with the CSS value inside, e.g., w-[450px].

2. Step 2: Check each option

   Only w-[450px] uses square brackets and includes units correctly.

3. Final Answer:

   w-[450px] -> Option B

4. Quick Check:

   Correct syntax = w-[450px] [OK]

Hint: Remember: square brackets around full CSS value with units [OK]

Common Mistakes:

• Omitting square brackets
• Missing units like px
• Using dash instead of brackets

3. What will be the width of the div rendered by this code?

<div class="w-[30rem] bg-blue-500 text-white p-4">Hello</div>

medium

A. Default width with blue background

B. Width of 30px with blue background

C. Width of 30rem (about 480px) with blue background

D. Width of 30rem but no background color

Solution

1. Step 1: Interpret the class w-[30rem]

   This sets the width to exactly 30rem, which is about 480 pixels (1rem ≈ 16px).

2. Step 2: Check other classes

   bg-blue-500 sets a blue background, text-white sets white text, and p-4 adds padding.

3. Final Answer:

   Width of 30rem (about 480px) with blue background -> Option C

4. Quick Check:

   Arbitrary width 30rem + blue bg = Width of 30rem (about 480px) with blue background [OK]

Hint: Remember rem units scale with root font size (~16px) [OK]

Common Mistakes:

• Confusing rem with px
• Ignoring background color class
• Assuming default width

4. Identify the error in this Tailwind class usage:

<div class="h-[100] bg-red-400">Error</div>

medium

A. Missing units inside the arbitrary value brackets

B. Incorrect use of square brackets

C. bg-red-400 is not a valid Tailwind class

D. Height cannot be set with arbitrary values

Solution

1. Step 1: Check the arbitrary value syntax

   The height is set as h-[100] but lacks units like px or rem.

2. Step 2: Understand CSS requirements

   CSS requires units for length values unless it's zero; so 100 alone is invalid.

3. Final Answer:

   Missing units inside the arbitrary value brackets -> Option A

4. Quick Check:

   Units required inside brackets [OK]

Hint: Always include units like px or rem inside brackets [OK]

Common Mistakes:

• Forgetting units inside arbitrary values
• Thinking brackets are wrong syntax
• Assuming Tailwind classes are invalid

5. You want to create a button with a custom border radius of 12px and a padding of 1.25rem using Tailwind. Which class combination correctly uses arbitrary values to achieve this?

hard

A. rounded-12px p-1.25rem

B. rounded-12 p-1.25rem

C. rounded-[12] p-[1.25]

D. rounded-[12px] p-[1.25rem]

Solution

1. Step 1: Use square brackets for arbitrary values

   Custom values must be inside square brackets with units, e.g., rounded-[12px] and p-[1.25rem].

2. Step 2: Check each option

   Only rounded-[12px] p-[1.25rem] correctly uses brackets and includes units for both border radius and padding.

3. Final Answer:

   rounded-[12px] p-[1.25rem] -> Option D

4. Quick Check:

   Arbitrary values need brackets + units [OK]

Hint: Use brackets and units for all custom CSS values [OK]

Common Mistakes:

• Omitting brackets
• Leaving out units
• Mixing syntax without brackets