Syllabus

On this page

Mobile-First & the Viewport

Badar KhalilUpdated September 30, 2026 9 min read

Mobile-First CSS and the Viewport: Complete Guide

Focus keyword: mobile-first CSS. Most web traffic today comes from phones. Mobile-first means you write the styles for the smallest screen first, then add complexity for larger screens with min-width media queries. Together with the viewport meta tag, it is the foundation of every responsive website. In this lesson you will learn how the viewport works, why mobile-first produces simpler CSS, how to use modern viewport units, how to handle notches with safe-area insets, how to size touch targets, and how to avoid the most common responsive bugs.

mobile-first design, viewport meta tag, width=device-width initial-scale=1, layout viewport vs visual viewport, min-width media queries, mobile-first vs desktop-first, svh lvh dvh units, 100vw horizontal scroll, safe-area-inset env(), viewport-fit cover, touch target size, WCAG 2.2 target size, pointer coarse, hover hover, progressive enhancement, device pixel ratio, responsive web design basics, mobile SEO, Core Web Vitals on mobile.

1. What Is Mobile-First?

Mobile-first is a way of writing CSS and of planning content. You start with a single column layout that works on a small phone, then you use @media (min-width: ...) to enhance the layout when more space is available. The base CSS is the mobile design, and media queries only add. This is the opposite of desktop-first, where you design a complex layout and then remove or undo things with max-width queries.

Simpler CSS: small screens get the least CSS and the simplest layout, which is usually faster on slow phones and networks.
Fewer overrides: you add rules instead of undoing rules.
Content priority: it forces you to decide what is really important.
Progressive enhancement: every browser gets a working baseline, and capable browsers get more.
SEO: search engines index the mobile version of a page first.

2. The Viewport Meta Tag

Without a viewport tag, a mobile browser pretends the screen is about 980px wide and then shrinks the page, so your media queries never match the real screen width. Always add this tag inside the head: <meta name='viewport' content='width=device-width, initial-scale=1'>.

width=device-width: the layout viewport equals the screen width in CSS pixels.
initial-scale=1: no initial zoom.
viewport-fit=cover: lets the page draw under notches and rounded corners. Combine it with safe-area insets.
interactive-widget=resizes-content: changes how the on-screen keyboard affects the layout in supporting browsers.
Never add user-scalable=no or maximum-scale=1. They block pinch zoom and fail accessibility rules, because people with low vision need to zoom.

3. Layout Viewport, Visual Viewport and CSS Pixels

The layout viewport is the area your CSS layout uses. The visual viewport is the part the user currently sees, and it changes when the user pinch-zooms or when the keyboard opens. A CSS pixel is not a physical pixel. A high density phone may have a device pixel ratio of 3, which means one CSS pixel is drawn with 3 by 3 device pixels. That is why a phone with a 1170 physical pixel width reports about 390 CSS pixels, and why you should serve sharper images to high density screens.

4. Mobile-First Media Queries

Write the base styles with no query, then use min-width:

Base: single column, full width.
@media (min-width: 600px): two columns.
@media (min-width: 960px): three columns, sidebar, larger spacing.

Choose breakpoints where your content starts to look bad, not only at device sizes. Use em or px consistently. You will study media queries in detail in the next lesson.

5. Viewport Units: vh, svh, lvh and dvh

On phones the address bar and toolbars appear and disappear, so 100vh can be taller than the visible area and push content out of sight. Modern units solve it:

svh: small viewport height, the visible height when browser bars are shown. Safe for content that must always be visible.
lvh: large viewport height, when bars are hidden.
dvh: dynamic viewport height, updates while bars move. Great for full screen sections, but it can cause layout changes while scrolling.
The same family exists for width and for logical directions: svw, lvw, dvw, svi, dvb.

A common pattern is min-height: 100svh for a hero and min-height: 100dvh for an app shell.

6. The 100vw Trap

width: 100vw includes the vertical scrollbar width on desktop, so the element becomes wider than the visible area and creates horizontal scrolling. Prefer width: 100% on block elements. A block element is already full width by default, so you often do not need a width at all. Also avoid fixed pixel widths larger than small phones, and use max-width: 100% for images and media.

7. Safe Area Insets for Notches

When you use viewport-fit=cover, use env(safe-area-inset-top), env(safe-area-inset-right), env(safe-area-inset-bottom) and env(safe-area-inset-left) to keep buttons and bars away from notches and gesture bars. Always give a fallback, for example env(safe-area-inset-bottom, 0px). Combine with max(): padding-bottom: max(1rem, env(safe-area-inset-bottom)).

8. Touch Targets

Fingers are less precise than a mouse. WCAG 2.2 requires at least 24 by 24 CSS pixels for a target (level AA) and recommends 44 by 44 pixels (level AAA). Many platform guidelines use 44 to 48 pixels. Add padding instead of only making text bigger, and keep space between targets so users do not tap the wrong one.

9. Input Capabilities: pointer and hover

Screen width does not tell you how the user interacts. A tablet can be wide and touch only, and a small laptop window can have a mouse. Use @media (pointer: coarse) for touch and @media (hover: hover) for devices that can really hover. Wrap hover-only effects inside (hover: hover) so touch devices do not get sticky hover states. Use any-pointer and any-hover when the device has more than one input.

10. Mobile-First Workflow

Write semantic HTML and read it without CSS. The reading order should make sense on a phone.
Add the viewport meta tag, a box-sizing reset and base typography.
Style the single column mobile layout.
Resize the browser wider. When the layout looks stretched or empty, add a breakpoint.
Enhance with grid, flexbox and larger spacing inside min-width queries.
Test in DevTools device mode, then on real phones, with zoom and with keyboard.

11. Performance on Mobile

Ship less CSS and JavaScript to small screens. Do not hide large desktop-only images with display none, because they may still download. Use responsive images.
Use system fonts or a small number of web fonts with font-display: swap.
Lazy load images below the fold.
Keep the layout stable to protect the Cumulative Layout Shift score.

12. Common Mistakes

Forgetting the viewport meta tag.
Blocking zoom with user-scalable=no.
Writing desktop-first CSS and then fighting max-width overrides.
Using 100vw and creating a horizontal scrollbar.
Using 100vh for full screen sections on phones and cutting off content.
Tiny tap targets placed close together.
Hover-only menus and tooltips that cannot be used on touch screens.
Testing only in a resized desktop window and never on a real device.

Key Takeaways

Add the viewport meta tag, write the small screen layout as your base, enhance with min-width queries, use svh, lvh and dvh instead of a risky 100vh, protect notches with safe-area insets, make touch targets large, and detect input with pointer and hover rather than guessing from width.

Try it Yourself HTML

<meta name='viewport' content='width=device-width, initial-scale=1'>
<style>
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; font: 1rem/1.6 system-ui, sans-serif; }
  .container { width: min(100% - 2rem, 1100px); margin-inline: auto; }
  header { background: #264653; color: #fff; padding: 1rem 0; }
  .grid { display: grid; gap: 1rem; padding-block: 1.5rem; }
  .card { background: #eef2f7; padding: 1rem; border-radius: 12px; }
  @media (min-width: 600px) { .grid { grid-template-columns: repeat(2, 1fr); } }
  @media (min-width: 960px) { .grid { grid-template-columns: repeat(3, 1fr); } }
</style>
<header><div class='container'><strong>Mobile-first page</strong></div></header>
<main class='container'>
  <div class='grid'>
    <div class='card'>1</div><div class='card'>2</div><div class='card'>3</div>
    <div class='card'>4</div><div class='card'>5</div><div class='card'>6</div>
  </div>
</main>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  body { font: 16px system-ui, sans-serif; padding: 16px; }
  .box { color: #fff; padding: 14px; margin-bottom: 12px; border-radius: 8px; }

  /* Mobile-first: base = small screen, then add */
  .mf { background: #2a9d8f; }
  .mf::after { content: ' (base styles)'; }
  @media (min-width: 600px) {
    .mf { background: #e76f51; }
    .mf::after { content: ' (600px and wider)'; }
  }

  /* Desktop-first: base = large screen, then undo */
  .df { background: #e76f51; }
  .df::after { content: ' (base styles)'; }
  @media (max-width: 599px) {
    .df { background: #2a9d8f; }
    .df::after { content: ' (599px and narrower, an override)'; }
  }
</style>
<div class='box mf'>Mobile-first with min-width</div>
<div class='box df'>Desktop-first with max-width</div>
<p>Resize the preview: both look the same, but the mobile-first CSS never has to undo anything.</p>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  body { font: 18px system-ui, sans-serif; padding: 16px; }
  .btn { min-height: 44px; min-width: 44px; padding: 0 18px; border: 0; border-radius: 10px; background: #0b5fff; color: #fff; font: inherit; margin: 0 8px 8px 0; }
  @media (pointer: coarse) { .btn { min-height: 52px; } }
  @media (hover: hover) { .btn:hover { background: #0847c4; } }
  .hint::after { content: 'Fine pointer (mouse or trackpad)'; }
  @media (pointer: coarse) { .hint::after { content: 'Coarse pointer (touch screen)'; } }
  .hover::after { content: 'Hover is NOT available'; }
  @media (hover: hover) { .hover::after { content: 'Hover is available'; } }
</style>
<button class='btn'>Save</button><button class='btn'>Share</button>
<p class='hint'>Primary input: </p>
<p class='hover'>Hover support: </p>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  body { margin: 0; font: 14px system-ui, sans-serif; padding: 12px; }
  .bars { display: flex; gap: 12px; align-items: flex-end; height: 40vh; border-bottom: 2px solid #888; }
  .bar { flex: 1; color: #fff; padding: 6px; border-radius: 6px 6px 0 0; }
  .vh { height: 30vh; background: #264653; }
  .svh { height: 30svh; background: #2a9d8f; }
  .lvh { height: 30lvh; background: #e9c46a; color: #111; }
  .dvh { height: 30dvh; background: #e76f51; }
</style>
<div class='bars'>
  <div class='bar vh'>30vh</div>
  <div class='bar svh'>30svh</div>
  <div class='bar lvh'>30lvh</div>
  <div class='bar dvh'>30dvh</div>
</div>
<p>On a phone with a retracting address bar, svh stays small, lvh stays large and dvh follows the bars. On desktop they are equal.</p>

Output

Press Run to execute.

Try it Yourself HTML

<meta name='viewport' content='width=device-width, initial-scale=1, viewport-fit=cover'>
<style>
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; font: 16px system-ui, sans-serif; padding: 16px 16px 90px; }
  .tabbar {
    position: fixed; inset: auto 0 0 0; display: flex; justify-content: space-around;
    background: #264653; color: #fff;
    padding: 10px 8px calc(10px + env(safe-area-inset-bottom, 0px));
  }
  .tabbar a { color: #fff; text-decoration: none; padding: 10px 14px; min-height: 44px; }
</style>
<h2>Safe area example</h2>
<p>The bottom bar adds env(safe-area-inset-bottom) so it stays above the gesture bar on phones with viewport-fit=cover.</p>
<nav class='tabbar' aria-label='Tabs'><a href='#'>Home</a><a href='#'>Search</a><a href='#'>Profile</a></nav>

Output

Press Run to execute.

Try it Yourself HTML

<style>
  *, *::before, *::after { box-sizing: border-box; }
  body { margin: 0; font: 16px system-ui, sans-serif; min-height: 100dvh; display: grid; grid-template-rows: auto 1fr auto; }
  header, footer { background: #264653; color: #fff; padding: 14px; }
  .layout { display: grid; gap: 12px; padding: 12px; grid-template-areas: 'nav' 'main' 'aside'; }
  nav { grid-area: nav; background: #e9c46a; padding: 12px; }
  main { grid-area: main; background: #8ecae6; padding: 12px; }
  aside { grid-area: aside; background: #ffb703; padding: 12px; }
  @media (min-width: 700px) {
    .layout { grid-template-columns: 180px 1fr; grid-template-areas: 'nav main' 'nav aside'; }
  }
  @media (min-width: 1000px) {
    .layout { grid-template-columns: 200px 1fr 240px; grid-template-areas: 'nav main aside'; }
  }
</style>
<header>Header</header>
<div class='layout'><nav>Nav</nav><main>Main content first in the flow</main><aside>Aside</aside></div>
<footer>Footer</footer>

Output

Press Run to execute.

Try it Yourself JAVASCRIPT

var width = window.innerWidth;
var height = window.innerHeight;

console.log('Layout viewport: ' + width + ' x ' + height + ' CSS pixels');
console.log('Device pixel ratio: ' + window.devicePixelRatio);

if (window.visualViewport) {
  console.log('Visual viewport scale: ' + window.visualViewport.scale);
}

var breakpoints = [
  { name: 'base (mobile)', min: 0 },
  { name: 'sm', min: 600 },
  { name: 'md', min: 960 }
];

var current = breakpoints[0];
breakpoints.forEach(function (bp) {
  if (width >= bp.min) { current = bp; }
});

console.log('Active mobile-first breakpoint: ' + current.name);

Output

Press Run to execute.

Exercise: Convert a Desktop-First Layout to Mobile-FirstHTML

The CSS below starts with the desktop layout and undoes it with max-width. Rewrite it mobile-first: the base styles must be a stacked single column, and a min-width: 700px query must create the row with a 240px sidebar.

Try it Yourself HTML

<style>
  .layout { display: flex; gap: 16px; }
  .side { width: 240px; background: #e9c46a; padding: 12px; }
  .main { flex: 1; background: #8ecae6; padding: 12px; }
  @media (max-width: 699px) {
    .layout { display: block; }
    .side { width: auto; margin-bottom: 16px; }
  }
</style>
<div class='layout'><aside class='side'>Sidebar</aside><main class='main'>Main</main></div>

Output

Press Run to execute.

Show expected output

Base styles are stacked with no max-width query, and @media (min-width: 700px) adds display: flex and the 240px sidebar

This is a self-check — compare your result with the expected output above.

Exercise: Fix the Horizontal Scroll and the ViewportHTML

Add the correct viewport meta tag and remove the horizontal scrollbar caused by width: 100vw. Also replace the fixed 900px width with a flexible width that never exceeds 900px, and do not block user zoom.

Try it Yourself HTML

<style>
  body { margin: 0; font-family: system-ui, sans-serif; }
  .hero { width: 100vw; background: #264653; color: #fff; padding: 24px; }
  .content { width: 900px; background: #eef2f7; padding: 16px; margin: 0 auto; }
</style>
<div class='hero'>Hero</div>
<div class='content'>Content</div>

Output

Press Run to execute.

Show expected output

A meta viewport tag with width=device-width, initial-scale=1 and no user-scalable=no, the hero without 100vw, and .content using width: min(100%, 900px) or max-width: 900px

This is a self-check — compare your result with the expected output above.

Was this page helpful?

Mobile-First CSS and the Viewport: Complete Guide

Trending keywords covered in this lesson

1. What Is Mobile-First?

2. The Viewport Meta Tag

3. Layout Viewport, Visual Viewport and CSS Pixels

4. Mobile-First Media Queries

5. Viewport Units: vh, svh, lvh and dvh

6. The 100vw Trap

7. Safe Area Insets for Notches

8. Touch Targets

9. Input Capabilities: pointer and hover

10. Mobile-First Workflow

11. Performance on Mobile

12. Common Mistakes

Key Takeaways