Tailwind CSS 4 - Overriding or replacing screen sizes (breakpoints)

Overview

Tailwind CSS version 4 introduces a significant architectural change by moving from JavaScript configuration to a CSS-first approach. This shift provides better performance, simpler configuration, and improved developer experience. Because of this change, extending or overriding screen sizes has evolved considerably.

In Tailwind CSS version 3 (and before), the config option was called 'screens', but in version 4, it's now referred to as 'breakpoint'. This change reflects the new CSS variable-based system that powers the framework.

Default Breakpoints in Tailwind CSS 4

For reference, here are the default breakpoints in Tailwind CSS 4:

• sm: 640px (small screens and up)
• md: 768px (medium screens and up)
• lg: 1024px (large screens and up)
• xl: 1280px (extra large screens and up)
• 2xl: 1536px (2x extra large screens and up)

Tailwind CSS version 3 - updating default screen size values

In Tailwind CSS 3, to update existing screen sizes, you would add the following code to your tailwind.config.js file:

/* Tailwind CSS 3 - tailwind.config.js */

export default {
  theme: {
    extend: {
      screens: {
        sm: "480px",
        md: "768px",
        lg: "976px",
      },
    },
  },
};

By adding this configuration into the extend section of the theme config, this will replace the values for sm, md, and lg.

Note: Tailwind CSS has 5 default values, so in this case, the values for xl and 2xl would remain unchanged.

Tailwind CSS version 3 - override default screen sizes

In Tailwind CSS 3, to completely override existing screen sizes, you would add the following code to your tailwind.config.js file:

/* Tailwind CSS 3 - tailwind.config.js */

export default {
  theme: {
    screens: {
      sm: "480px",
      md: "768px",
      lg: "976px",
    },
  },
};

By adding this configuration without the extend section of the theme config, this will replace the values for sm, md, and lg while also removing the values completely for xl and 2xl.

Tailwind CSS version 4 - updating default screen size values (now referred to as breakpoints)

In Tailwind CSS 4, to update existing screen sizes, you would add the following code to your global CSS file:

/* Tailwind CSS 4 - eg. main.css */

@import "tailwindcss";

@theme {
  --breakpoint-sm: 480px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 976px;
}

This configuration will replace the values for sm, md, and lg while leaving the values for xl and 2xl unchanged.

Practical Example

Here's a real-world scenario where you might want to customize breakpoints for better mobile-first design:

/* Custom breakpoints for a mobile-heavy audience */
@import "tailwindcss";

@theme {
  --breakpoint-xs: 320px; /* Extra small phones */
  --breakpoint-sm: 480px; /* Small phones */
  --breakpoint-md: 768px; /* Tablets */
  --breakpoint-lg: 976px; /* Small laptops */
  --breakpoint-xl: 1200px; /* Desktop */
}

This allows you to use classes like xs:text-sm md:text-base lg:text-lg for more granular responsive control.

Tailwind CSS version 4 - overriding default screen sizes (now referred to as breakpoints)

In Tailwind CSS 4, to completely override existing screen sizes, you would add the following code to your global CSS file:

/* Tailwind CSS 4 - eg. main.css */

@import "tailwindcss";

@theme {
  --breakpoint-*: initial;
  --breakpoint-sm: 480px;
  --breakpoint-md: 768px;
  --breakpoint-lg: 976px;
}

By adding the line --breakpoint-\*: initial;, this will reset all the default breakpoints and allow you to define them from scratch.

So the above configuration will replace the values for sm, md, and lg and remove the values for xl and 2xl.

Migration Tips from Tailwind CSS 3 to 4

When migrating your breakpoint configuration from Tailwind CSS 3 to 4, keep these points in mind:

1. Convert JavaScript to CSS Variables

// Tailwind CSS 3 - tailwind.config.js
screens: {
  'tablet': '640px',
  'laptop': '1024px',
  'desktop': '1280px',
}

Becomes:

/* Tailwind CSS 4 - main.css */

@import "tailwindcss";

@theme {
  --breakpoint-tablet: 640px;
  --breakpoint-laptop: 1024px;
  --breakpoint-desktop: 1280px;
}

2. Handle Complex Breakpoint Logic

Tailwind CSS 4 currently supports simple min-width breakpoints. If you were using complex media queries in v3, you may need to use custom CSS for advanced scenarios:

/* For complex breakpoints, use custom CSS */

@media (min-width: 768px) and (max-width: 1023px) {
  .tablet-only\:block {
    display: block;
  }
}

Troubleshooting Common Issues

Issue: Breakpoints not working after migration

Solution: Ensure you're importing tailwindcss in your CSS file and that your @theme block comes after the import.

Issue: Custom breakpoint names not recognized

Solution: Remember that breakpoint names must follow the --breakpoint- prefix pattern. Invalid characters will be ignored.

Issue: Existing v3 config still being used

Solution: Make sure you've updated your build process to use the new CSS-first approach and removed or updated your tailwind.config.js file.

Browser Compatibility

The CSS variable approach used in Tailwind CSS 4 is supported in all modern browsers:

• Chrome 49+
• Firefox 31+
• Safari 9.1+
• Edge 16+

For projects requiring Internet Explorer support, consider sticking with Tailwind CSS 3 or implementing appropriate fallbacks.