Runnable CSS Docs: Media Queries

Q: How do I write a media query for dark mode?

Use @media (prefers-color-scheme: dark) { ... }. It matches when the user's operating system or browser is set to a dark theme, and you can override colors or CSS variables inside it.

A media query in one example

A media query wraps CSS in a condition. The rules inside @media (min-width: 600px) only apply while the viewport is at least 600px wide:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Media query</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    .banner { padding: 16px; background: #f59e0b; color: #111827; }
    .banner::after { content: " (narrow: under 600px)"; }

    @media (min-width: 600px) {
      .banner { background: #2563eb; color: white; }
      .banner::after { content: " (wide: 600px or more)"; }
    }
  </style>
</head>
<body>
  <p class="banner">This box changes color at 600px</p>
  <p id="w"></p>
  <script>
    const show = () => { document.getElementById('w').textContent = 'This preview is ' + window.innerWidth + 'px wide.'; };
    addEventListener('resize', show);
    show();
  </script>
</body>
</html>

The preview is a frame, and a media query inside it measures the frame, not your screen. On a desktop it is about as wide as this article column, usually more than 600px, so the box is blue. Make your browser window narrow enough that the frame drops under 600px and it turns amber; the line under the box reports the frame's width live. On a phone the frame is already narrow, so you see the amber version.

The @media syntax

@media (min-width: 600px) { ... }                        /* one condition */
@media (min-width: 600px) and (max-width: 899px) { ... } /* both must be true */
@media (max-width: 599px), print { ... }                 /* either one (comma = or) */
@media not print { ... }                                 /* negation */
@media screen and (orientation: landscape) { ... }       /* media type plus a feature */
@media (width >= 600px) { ... }                          /* range syntax */
@media (600px <= width < 900px) { ... }                  /* a range with both ends */

and needs a space on both sides: (min-width: 600px)and(max-width: 900px) is invalid and the whole query is ignored. The range syntax (width >= 600px) is supported in current Chrome, Firefox and Safari and reads more clearly than min-width, especially for "up to but not including".

The features you will use most:

Feature	Matches when	Example
`min-width` / `width >=`	viewport is at least this wide	`(min-width: 768px)`
`max-width` / `width <=`	viewport is at most this wide	`(max-width: 767px)`
`orientation`	`portrait` (taller than wide) or `landscape`	`(orientation: landscape)`
`hover`	the main pointer can hover (`hover`) or not (`none`, most touch screens)	`(hover: hover)`
`pointer`	the main pointer is `fine` (mouse) or `coarse` (finger)	`(pointer: coarse)`
`prefers-color-scheme`	the user chose a `dark` or `light` theme	`(prefers-color-scheme: dark)`
`prefers-reduced-motion`	the user asked the system for less motion	`(prefers-reduced-motion: reduce)`
`print` (a media type)	the page is printed or saved as PDF	`@media print`

Mobile first: min-width breakpoints

Write the phone layout as the base CSS, then add min-width queries that change the layout as space grows. Each query only has to describe what changes:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Mobile first</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    .cards { display: grid; grid-template-columns: 1fr; gap: 10px; }
    .cards div { background: #16a34a; color: white; padding: 18px; border-radius: 6px; }

    @media (min-width: 480px) {
      .cards { grid-template-columns: 1fr 1fr; }
    }
    @media (min-width: 720px) {
      .cards { grid-template-columns: 1fr 1fr 1fr; }
    }
  </style>
</head>
<body>
  <div class="cards"><div>1</div><div>2</div><div>3</div><div>4</div><div>5</div><div>6</div></div>
  <p id="out"></p>
  <script>
    const show = () => {
      const n = getComputedStyle(document.querySelector('.cards')).gridTemplateColumns.split(' ').length;
      document.getElementById('out').textContent = innerWidth + 'px wide: ' + n + ' column(s)';
    };
    addEventListener('resize', show);
    show();
  </script>
</body>
</html>

In a wide desktop window the preview is over 720px, so you see three columns; the line under the grid reports the width and the column count. Narrow the window and it drops to two under 720px and to one under 480px. The order of the two queries matters: they are both true on a wide screen, and the later one wins, so min-width queries go from smallest to largest. (With max-width queries it is the reverse: largest first.)

Choosing breakpoints

There is no official list. These are common values and what they usually separate:

Breakpoint	Typically
`min-width: 640px`	large phones in landscape, small tablets
`min-width: 768px`	tablets in portrait
`min-width: 1024px`	tablets in landscape, small laptops
`min-width: 1280px`	desktops

A better method: start with the narrow layout, widen the window until something looks wrong (lines too long, cards too wide), and put a breakpoint there. Two or three breakpoints are enough for most pages. Often you need none at all: repeat(auto-fit, minmax(200px, 1fr)) in grid, flex-wrap, and clamp() adapt continuously.

Every page needs the viewport meta tag

Without this tag in the <head>, phone browsers lay the page out as if the screen were about 980px wide and then zoom out, so your min-width: 480px query is always true and your phone layout never shows:

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

The meta viewport page explains every value in it.

Dark mode with prefers-color-scheme

prefers-color-scheme follows the operating system's light or dark setting. The cleanest way to use it is to keep colors in CSS variables and change only the variables inside the query:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Dark mode</title>
  <style>
    :root { --bg: #ffffff; --text: #111827; --card: #e5e7eb; }

    @media (prefers-color-scheme: dark) {
      :root { --bg: #111827; --text: #f9fafb; --card: #1f2937; }
    }

    /* A theme toggle sets the same variables by hand */
    :root[data-theme="dark"] { --bg: #111827; --text: #f9fafb; --card: #1f2937; }
    :root[data-theme="light"] { --bg: #ffffff; --text: #111827; --card: #e5e7eb; }

    body { background: var(--bg); color: var(--text); font-family: system-ui, sans-serif; padding: 12px; }
    .card { background: var(--card); padding: 16px; border-radius: 8px; }
  </style>
</head>
<body>
  <div class="card">This card follows your system setting, or the button.</div>
  <p><button id="toggle">Switch theme</button></p>
  <p id="out"></p>
  <script>
    const mq = matchMedia('(prefers-color-scheme: dark)');
    const root = document.documentElement;
    const show = () => {
      document.getElementById('out').textContent =
        'Dark mode query matches: ' + mq.matches + '. Theme: ' + (root.dataset.theme || 'system');
    };
    document.getElementById('toggle').addEventListener('click', () => {
      const dark = root.dataset.theme ? root.dataset.theme === 'dark' : mq.matches;
      root.dataset.theme = dark ? 'light' : 'dark';
      show();
    });
    mq.addEventListener('change', show);
    show();
  </script>
</body>
</html>

In this preview the query can print false even when your system is set to dark: Chrome does not pass the system setting into a sandboxed frame like this one. The button sets the same variables by hand, which is how a site's theme toggle works. :root[data-theme] is more specific than the plain :root inside the query, so the reader's choice wins over the system. Save the example as a file and open it to see the query follow your system.

The script shows the second half of media queries: matchMedia() runs the same query from JavaScript, returns whether it matches now, and fires a change event when the answer changes. Use it when behavior (not just styling) depends on the screen, such as opening a menu differently on touch devices.

Motion works the same way. Wrap large or looping animations in a check for prefers-reduced-motion, as shown on the animation page.

Container queries: when the component should decide

A media query only knows the viewport. A card that sits in a wide main column and in a narrow sidebar on the same page needs to know its own space instead. That is a container query: mark the parent with container-type: inline-size, then use @container with the same conditions.

Drag the corner of the gray box to resize it. The card switches layout at 360px of box width, whatever the window size:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Container query</title>
  <style>
    body { font-family: system-ui, sans-serif; }
    .holder {
      container-type: inline-size;
      resize: horizontal;
      overflow: hidden;
      width: 480px;
      max-width: 100%;
      min-width: 160px;
      padding: 8px;
      background: #e5e7eb;
    }
    .card { display: grid; gap: 10px; background: white; padding: 10px; border-radius: 8px; }
    .pic { height: 70px; background: #2563eb; border-radius: 6px; }

    @container (min-width: 360px) {
      .card { grid-template-columns: 120px 1fr; }
    }
  </style>
</head>
<body>
  <div class="holder">
    <div class="card"><div class="pic"></div><p>Image beside the text when the box is 360px or wider, above it when narrower.</p></div>
  </div>
</body>
</html>

At its starting 480px the picture sits beside the text. Drag the box narrower than 376px (360px of content plus 8px of padding on each side) and the picture moves above the text. Container queries work in all current major browsers.

Styles for printing

@media print applies only when the page is printed or saved as a PDF. Hide navigation and buttons, and use dark text on white:

@media print {
  nav, .ad, button { display: none; }
  body { color: black; background: white; }
  a::after { content: " (" attr(href) ")"; } /* print the URL after each link */
}

Common mistakes

No viewport meta tag. Phones then report a wide layout viewport and small-screen queries never match.
Queries in the wrong order. Two true queries with the same selector: the later one wins. Order min-width queries from small to large.
Overlapping or gapping boundaries. max-width: 768px and min-width: 768px both match at exactly 768px. Use 767px for one of them, or the range syntax (width < 768px) and (width >= 768px).
No space after and. and( is invalid and the query is dropped silently.
Testing only by resizing a desktop window. Also check a real phone or the browser's device mode, which applies the phone's viewport, pixel ratio and touch.
Too many breakpoints. If every component needs its own, try grid auto-fit, flex-wrap or container queries instead.

Frequently Asked Questions

What is a media query in CSS?

A rule that applies the CSS inside it only when a condition about the device or window is true. @media (min-width: 600px) { ... } applies its styles only when the viewport is at least 600px wide, which is how one page adapts from phones to desktops.

Should I use min-width or max-width media queries?

Most sites write mobile first: the base CSS is for small screens and min-width queries add layout as the screen grows. max-width queries work the other way, starting from the desktop layout. Either works; mixing both on the same element leads to overlaps and gaps at the boundaries.

What are the standard media query breakpoints?

There is no official standard. Common choices are around 640px, 768px, 1024px and 1280px, but the better rule is to add a breakpoint where your own layout starts to look wrong, and to keep the number of breakpoints small.

Why is my media query not working on a phone?

The most common cause is a missing viewport meta tag. Without <meta name="viewport" content="width=device-width, initial-scale=1">, mobile browsers pretend the page is about 980px wide, so small-width queries never match. Also check that the query comes after the rules it overrides.

How do I write a media query for dark mode?

Use @media (prefers-color-scheme: dark) { ... }. It matches when the user's operating system or browser is set to a dark theme, and you can override colors or CSS variables inside it.

What is the difference between media queries and container queries?

A media query tests the viewport (the whole window). A container query, written with @container, tests the size of a parent element that you mark with container-type: inline-size. Use container queries for a component that appears in both wide and narrow places on the same page.

Related concepts