Square bracket notation for custom values in Tailwind - Deep Dive

Overview - Square bracket notation for custom values

What is it?

Square bracket notation in Tailwind CSS lets you write custom values directly inside class names using square brackets. This means you can use any size, color, or spacing value that Tailwind doesn't include by default. It helps you quickly add unique styles without changing configuration files. For example, you can write 'text-[22px]' to set font size to 22 pixels.

Why it matters

Tailwind provides many ready-made classes, but sometimes you need a style that isn't included. Without square bracket notation, you'd have to edit config files or write extra CSS. This notation saves time and keeps your code clean by letting you add custom styles right in your HTML. Without it, styling would be slower and more complicated.

Where it fits

Before learning this, you should know basic Tailwind classes and how utility-first CSS works. After this, you can explore advanced Tailwind features like plugins, theming, and responsive design. This concept is a bridge between using default utilities and customizing styles flexibly.

Mental Model

Core Idea

Square bracket notation lets you write any custom CSS value inside Tailwind class names, making Tailwind flexible beyond its default set.

Think of it like...

It's like having a toolbox with fixed-size screws but also a special tool that lets you create screws of any size on the spot when you need them.

Tailwind Classes
┌─────────────────────────────┐
│ Default classes (e.g., p-4) │
├─────────────────────────────┤
│ Custom classes [value]       │
│ e.g., text-[22px], bg-[#123abc] │
└─────────────────────────────┘

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' for padding or 'text-center' for text alignment. Each class applies a specific CSS style. These classes cover many common styles so you don't write CSS manually.

Result

You can style elements quickly using predefined class names.

Knowing how Tailwind classes work is essential before adding custom values.

2

Foundation

Limitations of Default Tailwind Values

Concept: Recognize that Tailwind's default classes cover many but not all style needs.

Tailwind has fixed scales for sizes, colors, and spacing. For example, padding classes go like p-1, p-2, p-3, etc. But what if you want padding of 7px and Tailwind doesn't have it? You need a way to add custom values.

Result

You see why default classes sometimes don't fit every design need.

Understanding these limits motivates learning custom value notation.

3

Intermediate

Introducing Square Bracket Notation Syntax

🤔Before reading on: do you think you can write any CSS value inside Tailwind classes using square brackets? Commit to yes or no.

Concept: Learn the syntax to write custom CSS values inside square brackets in class names.

Tailwind lets you write classes like 'text-[22px]' or 'bg-[#ff0000]'. The part inside brackets is raw CSS value. This overrides default scales and applies exactly what you write.

Result

You can now write any size, color, or other CSS value inline with Tailwind classes.

Knowing this syntax unlocks Tailwind's flexibility without config changes.

4

Intermediate

Using Square Brackets for Colors and Sizes

🤔Before reading on: can you use square brackets for colors like hex codes and for sizes like rem units? Commit to yes or no.

Concept: Apply square bracket notation for different CSS properties like colors and sizes.

Examples: - 'bg-[#123abc]' sets background color to a hex code. - 'w-[10rem]' sets width to 10 rem units. - 'text-[1.5rem]' sets font size. This works for any valid CSS value.

Result

You can customize many CSS properties directly in class names.

This shows the notation is versatile across CSS properties.

5

Intermediate

Handling Special Characters and Escaping

🤔Before reading on: do you think you need to escape special characters like # or / inside square brackets? Commit to yes or no.

Concept: Learn how to write special characters inside square brackets safely.

Some characters like '#' in colors or '/' in fractions need escaping or quotes in HTML. For example, 'bg-[#123abc]' works, but if you use slashes, you might write 'w-[calc(100%\-1rem)]'. Tailwind handles most cases but be careful with complex values.

Result

You can write complex CSS values safely inside square brackets.

Knowing escaping rules prevents syntax errors and broken styles.

6

Advanced

Combining Square Brackets with Responsive and State Variants

🤔Before reading on: can you use square bracket notation with responsive prefixes like md: or hover:? Commit to yes or no.

Concept: Use custom values inside square brackets together with Tailwind's responsive and state variants.

You can write classes like 'md:text-[20px]' or 'hover:bg-[#ff0000]'. This applies custom values only on certain screen sizes or states. This keeps your design responsive and interactive.

Result

Custom values work seamlessly with Tailwind's powerful variants.

This integration makes custom values practical in real-world responsive designs.

7

Expert

Performance and Maintainability Considerations

🤔Before reading on: do you think overusing square bracket notation can affect CSS file size or maintainability? Commit to yes or no.

Concept: Understand the trade-offs of using many custom values inline versus default classes or config extensions.

Every unique custom value generates a new CSS rule, increasing file size. Overusing them can make your code harder to read and maintain. Sometimes it's better to add values to Tailwind config or write reusable components. Balance flexibility with performance.

Result

You can make informed decisions about when to use square bracket notation.

Knowing these trade-offs helps write scalable and maintainable Tailwind projects.

Under the Hood

Tailwind's build process scans your HTML for class names. When it finds square bracket notation, it extracts the value inside brackets and generates a CSS rule with that exact value. This happens during build time, so the final CSS includes these custom rules. The notation uses a parser that recognizes the brackets and treats the content as raw CSS.

Why designed this way?

Tailwind was designed to be utility-first with a fixed set of classes for speed and consistency. But developers needed flexibility for unique designs. Square bracket notation was introduced to allow custom values without changing config or writing CSS, keeping the utility-first approach fast and simple.

HTML with classes
┌───────────────────────────────┐
│ <div class="text-[22px]">    │
└──────────────┬────────────────┘
               │
               ▼
Tailwind Parser detects [22px]
               │
               ▼
Generates CSS rule:
.text-\[22px\] { font-size: 22px; }
               │
               ▼
Final CSS includes custom rule
               │
               ▼
Browser applies style

Myth Busters - 4 Common Misconceptions

Quick: Does using square bracket notation always produce smaller CSS files? Commit yes or no.

Common Belief: Using square bracket notation keeps CSS files smaller because you write less code.

Reality: Each unique custom value creates a new CSS rule, which can increase CSS file size if overused.

Why it matters: Ignoring this can lead to bloated CSS files that slow down page loading.

Quick: Can you use any invalid CSS value inside square brackets and expect it to work? Commit yes or no.

Common Belief: You can put any text inside square brackets and Tailwind will apply it as a style.

Reality: Only valid CSS values work; invalid values cause no style or errors.

Why it matters: Using invalid values breaks styles and wastes debugging time.

Quick: Does square bracket notation replace the need to configure Tailwind's theme? Commit yes or no.

Common Belief: Square bracket notation means you never need to customize Tailwind's config file.

Reality: Config customization is still important for consistent design and reusability; square brackets are for quick one-offs.

Why it matters: Relying only on square brackets can lead to inconsistent styles and harder maintenance.

Quick: Can you use square bracket notation inside pseudo-elements like ::before? Commit yes or no.

Common Belief: Square bracket notation works everywhere, including pseudo-elements and complex selectors.

Reality: It only works in class names; pseudo-elements require separate CSS or plugins.

Why it matters: Misusing notation leads to styles not applying where expected.

Expert Zone

1

Square bracket notation supports arbitrary values but requires escaping special characters in some contexts, which can be tricky in JSX or frameworks.

2

Using square brackets with dynamic values in frameworks like React needs careful handling to avoid invalid class names or runtime errors.

3

Tailwind's JIT compiler generates CSS on demand, so square bracket classes only appear if used in source files, keeping CSS size optimized.

When NOT to use

Avoid heavy use of square bracket notation for common values that can be added to Tailwind's config theme for consistency and better caching. For complex selectors or pseudo-elements, use custom CSS or plugins instead.

Production Patterns

In production, developers use square bracket notation for unique one-off styles like exact spacing or colors from a design spec. They combine it with responsive and state variants for polished UI. Teams often limit its use to keep codebase maintainable.

Connections

CSS Variables

Builds-on

Knowing how square bracket notation injects raw CSS values helps understand how CSS variables can be used inside Tailwind classes for dynamic theming.

JavaScript Template Literals

Similar pattern

Both use bracket-like syntax to embed dynamic values inline, showing a pattern of mixing fixed structure with flexible content.

Mathematical Function Parameters

Analogy in abstraction

Just like functions accept parameters to customize behavior, square bracket notation lets you pass custom values to Tailwind utilities, making them more flexible.

Common Pitfalls

#1 Writing invalid CSS value inside brackets.

Wrong approach:

text-[22pixels]

Correct approach:

text-[22px]

Root cause:

Misunderstanding CSS units causes invalid values that don't apply styles.

#2 Using square bracket notation excessively for common values.

Wrong approach:

p-[8px] p-[16px] p-[24px]

Correct approach:

Use Tailwind's default padding classes like p-2, p-4, p-6 or extend config for custom scales.

Root cause:

Not knowing when to extend Tailwind config leads to bloated CSS and inconsistent styles.

#3 Not escaping special characters in complex values.

Wrong approach:

w-[calc(100%-1rem)]

Correct approach:

w-[calc(100%\-1rem)]

Root cause:

Ignoring CSS escaping rules causes build errors or broken styles.

Key Takeaways

Square bracket notation lets you write any valid CSS value inside Tailwind class names for quick custom styling.

It works with sizes, colors, spacing, and can be combined with responsive and state variants.

Overusing custom values can increase CSS size and reduce maintainability, so balance is key.

Understanding escaping and valid CSS syntax is essential to avoid errors.

This feature bridges Tailwind's utility-first approach with flexible, unique design needs.