Mobile-First CSS in WordPress: Using min-width and Where to Add It

This article is a localized edition of the Japanese original. Read the Japanese original

Mobile-first CSS treats the styles for narrow smartphone screens as the base, then adds rules for wider screens with min-width media queries. It is the reverse of "desktop-first," where you write desktop styles first and override them for narrow screens with max-width. This article explains where to write CSS in WordPress and the concrete steps for writing it mobile-first.

Mobile-first vs. desktop-first

Here is the same layout, one column on narrow screens and three columns on wide screens, written both ways.

Desktop-first (override for narrow screens with max-width):

.cards { display: grid; grid-template-columns: repeat(3, 1fr); gap: 2rem; }

@media (max-width: 1023px) {
  .cards { grid-template-columns: repeat(2, 1fr); }
}
@media (max-width: 599px) {
  .cards { grid-template-columns: 1fr; gap: 1rem; }
}

Mobile-first (add rules for wider screens with min-width):

.cards { display: grid; grid-template-columns: 1fr; gap: 1rem; }

@media (min-width: 600px) {
  .cards { grid-template-columns: repeat(2, 1fr); gap: 2rem; }
}
@media (min-width: 1024px) {
  .cards { grid-template-columns: repeat(3, 1fr); }
}

With mobile-first, the styles outside media queries apply to every screen, and more rules are added as the screen gets wider. The rules smartphones load stay simple, and you write fewer overrides. Be careful: if you call it "mobile-first" but start with a max-width media query, you end up with the same structure as desktop-first.

Prerequisite: check the viewport setting

Smartphone browsers shrink pages without a viewport setting as if they were wide screens, so media queries don't work as expected. Check the page source for a meta element like this.

<meta name="viewport" content="width=device-width, initial-scale=1" />

With block themes, WordPress core (5.8 and later) outputs this meta element. Classic themes usually include it in the theme's header.php or a similar file. If an old custom theme lacks it, add it inside <head> in header.php.

Where to write CSS

If you edit the parent theme's files directly, a theme update overwrites and erases your changes. Write CSS in one of these places instead.

For a lot of CSS, or when you rebuild the whole theme mobile-first, putting a CSS file in a child theme and loading it is the easiest to maintain.

Load a CSS file from a child theme

Load it from the child theme's functions.php using the wp_enqueue_scripts hook. Using filemtime() as the version number makes browsers fetch a fresh copy whenever you update the file.

<?php
add_action( 'wp_enqueue_scripts', function () {
	$file = get_stylesheet_directory() . '/css/mobile-first.css';

	wp_enqueue_style(
		'mychild-mobile-first',
		get_stylesheet_directory_uri() . '/css/mobile-first.css',
		array(),
		file_exists( $file ) ? filemtime( $file ) : null
	);
}, 20 );

The priority is 20 so the file loads after the parent theme's styles (usually registered at the default priority 10), letting selectors of the same specificity override them.

Steps for writing mobile-first CSS

1. Decide on breakpoints

Choose breakpoints by the width at which the layout starts to break, not by device model. Two are enough to start. The examples in this article use 600px (where the layout goes to two columns) and 1024px (where it goes to three columns or shows a sidebar). If your theme has its own breakpoints, matching them keeps your switch points aligned with the theme's CSS.

2. Write smartphone styles outside media queries

First, write the smartphone styles without any media query.

/* Base styles for every screen (for smartphones) */
body {
  font-size: 1rem;
  line-height: 1.8;
}

.site-content {
  padding-inline: 1rem;
}

img {
  max-width: 100%;
  height: auto;
}

.sidebar {
  margin-top: 2rem;
}

3. Add wider-screen styles with min-width

Next, put only what changes on wider screens into min-width media queries. Order them from the smallest width up.

@media (min-width: 600px) {
  .site-content {
    padding-inline: 2rem;
  }
}

@media (min-width: 1024px) {
  .site-content {
    display: grid;
    grid-template-columns: minmax(0, 1fr) 300px;
    gap: 3rem;
    max-width: 1200px;
    margin-inline: auto;
  }

  .sidebar {
    margin-top: 0;
  }
}

With min-width media queries, more blocks apply at once the wider the screen is. Later rules win, so ordering from the smallest width up is essential.

4. Consider approaches without media queries

Font sizes and the number of card columns can also adapt to the screen width without media queries.

/* Heading that scales between 1.5rem and 2.25rem with the screen width */
h1 {
  font-size: clamp(1.5rem, 1.2rem + 1.5vw, 2.25rem);
}

/* Each card is at least 16rem wide; create as many columns as fit */
.cards {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(16rem, 1fr));
  gap: 1rem;
}

In block themes, the font size settings in theme.json also offer a way to scale text with the screen width (fluid typography).

Converting existing CSS to mobile-first

When you convert desktop-first CSS, working in this order makes breakage easier to spot.

1. Take screenshots of the current state at smartphone, tablet, and desktop widths
2. Move the contents of the narrowest max-width media query out of the media query (into the base styles)
3. Move the desktop rules that were in the base styles into min-width media queries
4. Check each width and compare with the screenshots from step 1

If the parent theme's CSS is desktop-first, its max-width media queries can override the base styles you wrote in the child theme. Work with the browser's developer tools open so you can see which rules apply.

Check the result

• Use the device mode of your browser's developer tools (the "device toolbar" in Chrome and Edge) and change the width as you check
• Check that the layout switches on either side of each breakpoint (for example, 599px and 600px)
• Developer tools and real devices differ in things like address bar height, so finish by checking on a real smartphone
• If you use a caching plugin or a CDN, clear the cache after changing CSS

Summary

• Mobile-first means writing smartphone styles outside media queries and adding wider-screen rules with min-width. Starting from max-width gives you the opposite structure
• Without the viewport meta element, media queries don't work as expected. Block themes get it from WordPress core
• Don't write CSS in the parent theme. Use Additional CSS, the Site Editor's "Styles," or a child theme
• Order min-width media queries from the smallest width up
• clamp() and auto-fit let you use fewer media queries

Related articles:

• How to create a WordPress child theme
• How to set styles with theme.json
• How responsive images work in WordPress

Questions about WordPress? The publisher of this site is based in Japan and replies in Japanese. Contact (Japanese)