Tailwind CSS v4 Configuration Examples
This document provides practical examples of how to configure Tailwind CSS v4 using
the new CSS-based configuration approach. These examples show how to migrate
common configuration patterns from v3's JavaScript configuration to v4's CSS
configuration.
Basic Configuration Examples
Colors
v3 (tailwind.config.js):
module.exports = {
theme: {
colors: {
blue: {
50: '#eff6ff',
100: '#dbeafe',
500: '#3b82f6',
900: '#1e3a8a',
},
custom: '#ff5733',
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
--color-blue-50: #eff6ff;
--color-blue-100: #dbeafe;
--color-blue-500: #3b82f6;
--color-blue-900: #1e3a8a;
--color-custom: #ff5733;
}
Typography
v3 (tailwind.config.js):
module.exports = {
theme: {
fontFamily: {
sans: ['Inter', 'sans-serif'],
serif: ['Merriweather', 'serif'],
mono: ['Fira Code', 'monospace'],
display: ['Oswald', 'sans-serif'],
},
fontSize: {
xs: ['0.75rem', { lineHeight: '1rem' }],
sm: ['0.875rem', { lineHeight: '1.25rem' }],
base: ['1rem', { lineHeight: '1.5rem' }],
lg: ['1.125rem', { lineHeight: '1.75rem' }],
xl: ['1.25rem', { lineHeight: '1.75rem' }],
'2xl': ['1.5rem', { lineHeight: '2rem' }],
'3xl': ['1.875rem', { lineHeight: '2.25rem' }],
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
--font-sans: "Inter", sans-serif;
--font-serif: "Merriweather", serif;
--font-mono: "Fira Code", monospace;
--font-display: "Oswald", sans-serif;
--text-xs: 0.75rem;
--text-sm: 0.875rem;
--text-base: 1rem;
--text-lg: 1.125rem;
--text-xl: 1.25rem;
--text-2xl: 1.5rem;
--text-3xl: 1.875rem;
--leading-xs: 1rem;
--leading-sm: 1.25rem;
--leading-base: 1.5rem;
--leading-lg: 1.75rem;
--leading-xl: 1.75rem;
--leading-2xl: 2rem;
--leading-3xl: 2.25rem;
}
Spacing
v3 (tailwind.config.js):
module.exports = {
theme: {
spacing: {
px: '1px',
0: '0',
0.5: '0.125rem',
1: '0.25rem',
1.5: '0.375rem',
2: '0.5rem',
2.5: '0.625rem',
3: '0.75rem',
3.5: '0.875rem',
4: '1rem',
// Custom values
'4.5': '1.125rem',
'13': '3.25rem',
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
--spacing-px: 1px;
--spacing-0: 0;
--spacing-0\.5: 0.125rem;
--spacing-1: 0.25rem;
--spacing-1\.5: 0.375rem;
--spacing-2: 0.5rem;
--spacing-2\.5: 0.625rem;
--spacing-3: 0.75rem;
--spacing-3\.5: 0.875rem;
--spacing-4: 1rem;
/* Custom values */
--spacing-4\.5: 1.125rem;
--spacing-13: 3.25rem;
}
Breakpoints
v3 (tailwind.config.js):
module.exports = {
theme: {
screens: {
'sm': '640px',
'md': '768px',
'lg': '1024px',
'xl': '1280px',
'2xl': '1536px',
'custom': '1400px',
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
--breakpoint-sm: 640px;
--breakpoint-md: 768px;
--breakpoint-lg: 1024px;
--breakpoint-xl: 1280px;
--breakpoint-2xl: 1536px;
--breakpoint-custom: 1400px;
}
Advanced Configuration Examples
Custom Gradients
v3 (tailwind.config.js):
module.exports = {
theme: {
extend: {
backgroundImage: {
'gradient-custom': 'linear-gradient(to right, var(--tw-gradient-stops))',
'gradient-radial': 'radial-gradient(var(--tw-gradient-stops))',
},
gradientColorStops: {
'custom-start': '#3b82f6',
'custom-end': '#8b5cf6',
},
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
--gradient-custom: linear-gradient(to right, var(--tw-gradient-stops));
--gradient-radial: radial-gradient(var(--tw-gradient-stops));
--gradient-from-custom-start: #3b82f6;
--gradient-to-custom-end: #8b5cf6;
}
Custom Animations and Transitions
v3 (tailwind.config.js):
module.exports = {
theme: {
extend: {
animation: {
'spin-slow': 'spin 3s linear infinite',
'bounce-slow': 'bounce 2s infinite',
'custom': 'custom 2s ease-in-out infinite',
},
keyframes: {
custom: {
'0%, 100%': { transform: 'translateY(0)' },
'50%': { transform: 'translateY(-25px)' },
},
},
transitionProperty: {
'height': 'height',
'spacing': 'margin, padding',
},
transitionDuration: {
'2000': '2000ms',
},
transitionTimingFunction: {
'bounce-in': 'cubic-bezier(0.68, -0.55, 0.265, 1.55)',
},
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
--animation-spin-slow: spin 3s linear infinite;
--animation-bounce-slow: bounce 2s infinite;
--animation-custom: custom 2s ease-in-out infinite;
--keyframes-custom: {
0%, 100% { transform: translateY(0); }
50% { transform: translateY(-25px); }
};
--transition-property-height: height;
--transition-property-spacing: margin, padding;
--transition-duration-2000: 2000ms;
--ease-bounce-in: cubic-bezier(0.68, -0.55, 0.265, 1.55);
}
Custom Plugins and Utilities
v3 (tailwind.config.js):
const plugin = require('tailwindcss/plugin')
module.exports = {
theme: {
extend: {
// Theme extensions
},
},
plugins: [
plugin(function({ addUtilities, theme }) {
const newUtilities = {
'.text-shadow-sm': {
textShadow: '0 1px 2px rgba(0, 0, 0, 0.05)',
},
'.text-shadow': {
textShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
},
'.text-shadow-lg': {
textShadow: '0 4px 6px rgba(0, 0, 0, 0.15)',
},
}
addUtilities(newUtilities)
}),
],
}
v4 (CSS):
@import "tailwindcss";
@theme {
/* Theme variables */
}
@layer utilities {
.text-shadow-sm {
text-shadow: 0 1px 2px rgba(0, 0, 0, 0.05);
}
.text-shadow {
text-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}
.text-shadow-lg {
text-shadow: 0 4px 6px rgba(0, 0, 0, 0.15);
}
}
Complex Color Configuration with Modern Color Formats
v3 (tailwind.config.js):
module.exports = {
theme: {
extend: {
colors: {
primary: {
50: '#f0f9ff',
100: '#e0f2fe',
200: '#bae6fd',
300: '#7dd3fc',
400: '#38bdf8',
500: '#0ea5e9',
600: '#0284c7',
700: '#0369a1',
800: '#075985',
900: '#0c4a6e',
},
secondary: {
DEFAULT: '#8b5cf6',
dark: '#6d28d9',
},
},
},
},
}
v4 (CSS):
@import "tailwindcss";
@theme {
/* Using modern OKLCH color format for better color reproduction */
--color-primary-50: oklch(0.98 0.01 240);
--color-primary-100: oklch(0.95 0.02 240);
--color-primary-200: oklch(0.90 0.04 240);
--color-primary-300: oklch(0.85 0.06 240);
--color-primary-400: oklch(0.75 0.10 240);
--color-primary-500: oklch(0.65 0.15 240);
--color-primary-600: oklch(0.55 0.18 240);
--color-primary-700: oklch(0.45 0.16 240);
--color-primary-800: oklch(0.35 0.12 240);
--color-primary-900: oklch(0.25 0.08 240);
--color-secondary: oklch(0.65 0.20 280);
--color-secondary-dark: oklch(0.50 0.22 280);
}
Using CSS Variables in Custom Components
v3 (tailwind.config.js + CSS):
// tailwind.config.js
module.exports = {
theme: {
extend: {
colors: {
brand: '#3b82f6',
},
spacing: {
'18': '4.5rem',
},
borderRadius: {
'xl': '1rem',
},
},
},
}
/* components.css */
.custom-card {
/* Hard to reference theme values directly */
background-color: #3b82f6;
padding: 4.5rem;
border-radius: 1rem;
}
v4 (CSS):
@import "tailwindcss";
@theme {
--color-brand: #3b82f6;
--spacing-18: 4.5rem;
--radius-xl: 1rem;
}
/* Now you can directly reference theme variables */
.custom-card {
background-color: var(--color-brand);
padding: var(--spacing-18);
border-radius: var(--radius-xl);
}
Dynamic Utility Values
One of the powerful features in Tailwind CSS v4 is the ability to use dynamic utility
values without extending the configuration:
<!-- v3 required configuration extension for arbitrary values -->
<div class="text-[22px] p-[18px] rounded-[12px]">
Custom sizing without configuration
</div>
<!-- v4 supports dynamic values natively -->
<div class="text-[22px] p-[18px] rounded-[12px]">
Custom sizing without configuration
</div>
Conclusion
These examples demonstrate how to migrate various configuration patterns from
Tailwind CSS v3's JavaScript-based approach to v4's CSS-based approach. The new
configuration system offers several advantages:
1. Simplicity: Configuration is done directly in CSS, reducing the number of files to
manage
2. Accessibility: Theme variables are exposed as CSS variables, making them
accessible throughout your styles
3. Flexibility: The CSS-based approach allows for more dynamic and responsive
configurations
4. Performance: The new system is optimized for speed, with builds up to 5x faster
For more complex configurations or specific use cases, refer to the official Tailwind CSS
documentation or use the automated upgrade tool: npx @tailwindcss/upgrade .
