Tailwind CSS - Customizing Screens

Tailwind CSS - Customizing Screens

Screens are the cornerstone of responsive design in Tailwind CSS. They define the breakpoints (e.g., sm, md, lg) that allow you to apply different styles at different viewport sizes. Customizing these screens lets you tailor your project’s responsive behavior to match your specific design system.

All screen customizations happen within the theme.screens object in your tailwind.config.js file. By default, Tailwind uses a mobile-first min-width system.

Default Breakpoints

tailwind.config.js

module.exports = {
  theme: {
    screens: {
      'sm': '640px',  // => @media (min-width: 640px) { ... }
      'md': '768px',  // => @media (min-width: 768px) { ... }
      'lg': '1024px', // => @media (min-width: 1024px) { ... }
      'xl': '1280px', // => @media (min-width: 1280px) { ... }
      '2xl': '1536px',// => @media (min-width: 1536px) { ... }
    }
  }
}

Extending vs. Overriding

You have two main strategies for customization: extending or overriding.

Extending Screens (Recommended)

To add a new breakpoint or modify an existing one while keeping the defaults, use the extend key. This is the most common approach.

tailwind.config.js

module.exports = {
  theme: {
    extend: {
      screens: {
        'lg': '1150px', // Overrides the default 'lg' breakpoint
        '3xl': '1920px', // Adds a new '3xl' breakpoint
      },
    },
  },
}

Overriding All Screens

To completely replace Tailwind’s default breakpoints with your own set, define your screens directly under theme. Warning: This will remove all default breakpoints (sm, md, etc.) unless you redefine them.

tailwind.config.js

module.exports = {
  theme: {
    screens: {
      'tablet': '768px',
      'laptop': '1024px',
      'desktop': '1280px',
    },
  }
}

Your responsive modifiers will now be tablet:, laptop:, and desktop:.

Advanced Customization

Adding a Smaller Breakpoint

Because breakpoints must be ordered from smallest to largest, you cannot use extend to add a smaller breakpoint (as it would be appended to the end). Instead, import the default theme and spread it into your custom configuration.

tailwind.config.js

const defaultTheme = require('tailwindcss/defaultTheme')

module.exports = {
  theme: {
    screens: {
      'xs': '475px', // Your new, smaller breakpoint
      ...defaultTheme.screens,
    },
  },
}

Max-Width Breakpoints (Desktop-First)

If your project follows a desktop-first approach, you can define breakpoints using max-width. Important: When using max-width, you must list your breakpoints from largest to smallest.

tailwind.config.js

module.exports = {
  theme: {
    screens: {
      'xl': {'max': '1279px'}, // => @media (max-width: 1279px) { ... }
      'lg': {'max': '1023px'}, // => @media (max-width: 1023px) { ... }
      'md': {'max': '767px'},  // => @media (max-width: 767px) { ... }
      'sm': {'max': '639px'},  // => @media (max-width: 639px) { ... }
    }
  }
}

Fixed-Range Breakpoints

To target a specific range, provide an object with both a min and a max key.

tailwind.config.js

module.exports = {
  theme: {
    extend: {
      screens: {
        // Targets only devices between 640px and 767px
        'sm-only': {'min': '640px', 'max': '767px'},
      },
    },
  }
}

Custom Media Queries with raw

For complete control, the raw key lets you write any media query you need. This is powerful for targeting device features like orientation, pointer type, or user preferences.

tailwind.config.js

module.exports = {
  theme: {
    extend: {
      screens: {
        'landscape': {'raw': '(orientation: landscape)'},
        'portrait': {'raw': '(orientation: portrait)'},
        'motion-ok': {'raw': '(prefers-reduced-motion: no-preference)'},
      }
    }
  }
}

You can then use classes like landscape:grid-cols-2 or motion-ok:transition.