Configuring Global Styles and Container in Tailwind CSS v4

Problem Statement

In Tailwind CSS v4, the standard tailwind.config.js file is no longer created by default. This paradigm shift leaves developers uncertain about configuring global classes like the container utility or adding custom responsive and hover styles. Common challenges include:

• Setting container max-width at specific breakpoints (e.g., xl)
• Defining custom reusable classes with hover states
• Implementing responsive variants for custom utilities

Solution Overview

Tailwind CSS v4 introduces CSS-first configuration as its default approach while maintaining backward compatibility for JavaScript configuration. Here are two robust methods to configure global styles:

---

Method 1: JavaScript Configuration (Backward Compatible)

Re-enable traditional tailwind.config.js with these steps:

1. Create tailwind.config.js manually in your project root:

// tailwind.config.js
export default {
  theme: {
    container: {
      center: true,
      padding: '2rem',
      screens: {
        xl: '1280px' // Custom max-width for xl breakpoint
      }
    }
  }
};

2. Add @config directive to your main CSS file:

/* main.css */
@config "./tailwind.config.js";
@tailwind base;
@tailwind components;
@tailwind utilities;

---

Method 2: CSS-First Configuration (Recommended for v4)

Define global styles directly in your CSS using new directives:

/* main.css */
@theme {
  /* Define custom breakpoints */
  --breakpoint-xl: 1280px;

  /* Container configuration */
  --container-max-width: var(--breakpoint-xl);
}

@layer components {
  /* Custom responsive container */
  .custom-container {
    @apply max-w-[var(--container-max-width)] mx-auto px-8;
  }

  /* Custom card with hover states */
  .custom-card {
    @apply bg-white p-6 rounded-xl border border-gray-200;
    transition: transform 0.3s, box-shadow 0.3s;
    
    &:hover {
      @apply shadow-lg;
      transform: translateY(-5px);
    }
  }
}

---

Key Features Explained

1. Container Configuration
   In CSS-first mode, control max-width with CSS variables:

   @theme {
     --container-max-width: 1200px; /* Default */
     --breakpoint-3xl: 1920px; /* New breakpoint */
   }
   
   /* Usage in HTML */
   <div class="container max-w-[var(--breakpoint-3xl)]">

2. Creating Custom Responsive Classes
   Use @layer with responsive modifiers:

   @layer utilities {
     .bg-brand-gradient {
       background: linear-gradient(90deg, #ff8a00, #ff0080);
     }
     
     @screen md {
       .bg-brand-gradient-md {
         background: linear-gradient(90deg, #00ff87, #60efff);
       }
     }
   }

3. Hover States
   Combine CSS nesting with Tailwind's hover variants:

   @layer components {
     .btn-custom {
       @apply py-2 px-4 rounded-lg;
       @apply hover:bg-indigo-700 hover:-translate-y-0.5;
     }
   }

---

Pro Tips

• Plugins: Use CSS-first plugin loading

  @plugin "@tailwindcss/typography";

• Theme Extension: Override design tokens with @theme

  @theme {
    --color-brand: oklch(0.62 0.17 256.8);
    --space-sm: clamp(0.5rem, 0.5rem + 0.5vw, 1rem);
  }

• Performance: Prefer CSS variables over static values for dynamic changes:

  /* Recommended */
  --custom-value: 1rem;
  
  /* Avoid */
  margin-top: 1rem;

Transition Timeline

While JavaScript configuration remains supported, Tailwind recommends adopting CSS-first methods for future-proof projects. New features like @theme and CSS variables offer better performance and theming capabilities.

For complete documentation, visit the official Tailwind CSS v4 Functions and Directives guide.