What You’ll Learn

The aspect-ratio media feature matches the viewport’s width-to-height proportion. Adapt layouts for widescreen desktops, square tablets, and tall phone screens without guessing from pixel width alone.

Introduction

The @media rule applies CSS when certain device conditions are met. The aspect-ratio media feature checks the viewport’s width-to-height ratio — for example, whether the browser window is wider than it is tall (landscape) or taller than it is wide (portrait).

This is especially useful for responsive design. Two devices may share the same pixel width but have very different shapes. A phone in landscape and a narrow desktop window can both be wide, but their aspect ratios tell you how much vertical space is available for content.

Definition and Usage

Write ratios as width/height inside parentheses: @media (aspect-ratio: 16/9), @media (min-aspect-ratio: 4/3), or @media (max-aspect-ratio: 1/1). When the viewport matches, the nested CSS rules apply.

📝 Syntax

Use aspect-ratio features inside an @media block. Ratios are written as two integers separated by a slash:

@media (aspect-ratio: 16/9) {
  /* Exact 16:9 viewport */
}

@media (min-aspect-ratio: 4/3) {
  /* Viewport is 4:3 or wider */
}

@media (max-aspect-ratio: 1/1) {
  /* Viewport is square or taller (portrait) */
}

Feature Variants

• aspect-ratio — Matches an exact viewport ratio such as 16/9 or 4/3.
• min-aspect-ratio — Matches when the viewport ratio is equal to or wider than the value (more horizontal).
• max-aspect-ratio — Matches when the viewport ratio is equal to or narrower/taller than the value (more vertical).

Basic Example

body {
  background-color: #dbeafe;
}

@media (aspect-ratio: 16/9) {
  body {
    background-color: #bbf7d0;
  }
}

Media Feature vs CSS Property

Default Value

There is no default value. The browser evaluates the current viewport dimensions at runtime.

Syntax Rules

• Write ratios as two integers with a slash: 16/9, not 16:9 in the media query.
• Spaces around the slash are optional but the slash is required.
• Combine with width queries: @media (min-width: 48rem) and (min-aspect-ratio: 16/9).
• Exact aspect-ratio matches are rare; prefer min- and max- ranges.
• Resize the browser window to test — DevTools device mode helps simulate ratios.

Related Topics

• aspect-ratio property — set element width-to-height ratio
• any-pointer — detect pointer precision
• width property — element sizing alongside media queries

When to Use aspect-ratio

Reach for aspect-ratio media queries when viewport shape matters:

• Portrait vs landscape — Stack content vertically on tall phone screens; use side-by-side columns on widescreen windows.
• Hero sections — Show cinematic full-width heroes only when min-aspect-ratio: 16/9 matches.
• Video players — Adjust padding and controls when the viewport is wider or taller than 16:9.
• Dashboard layouts — Reveal extra panels on ultrawide monitors with high aspect ratios.
• Combined with width — Fine-tune tablet layouts where width alone is ambiguous.

Examples Gallery

Practice aspect-ratio with backgrounds, portrait layouts, hero sections, and combined media queries.

body {
  background-color: #dbeafe;
  font-family: system-ui, sans-serif;
  padding: 2rem;
}

@media (aspect-ratio: 16/9) {
  body {
    background-color: #bbf7d0;
  }
}

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

@media (max-aspect-ratio: 1/1) {
  .grid {
    grid-template-columns: 1fr;
  }
}

.hero {
  padding: 2rem 1.5rem;
  background: #334155;
  color: #fff;
  text-align: center;
}

@media (min-aspect-ratio: 16/9) {
  .hero {
    padding: 4rem 2rem;
    background: linear-gradient(135deg, #1e3a8a, #2563eb);
  }
  .hero h1 {
    font-size: 2.5rem;
  }
}

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

@media (min-width: 48rem) and (min-aspect-ratio: 4/3) {
  .cards {
    grid-template-columns: repeat(3, 1fr);
  }
}

@media (min-aspect-ratio: 4/3) {
  body {
    background-color: #fdf2f8;
  }
}

💬 Usage Tips

• Prefer ranges — Use min-aspect-ratio and max-aspect-ratio instead of exact ratios for reliable matches.
• Portrait phones — max-aspect-ratio: 1/1 is a simple portrait detector.
• Combine with width — Pair aspect-ratio with min-width to avoid layout jumps on odd window sizes.
• Test by resizing — Drag the browser corner to see when queries fire; use DevTools responsive mode.
• Element vs viewport — Use the aspect-ratio property for boxes; use the media feature for page layout.

⚠️ Common Pitfalls

• Exact ratio fragility — aspect-ratio: 16/9 matches only precisely; one pixel off and styles won’t apply.
• Confusing with orientation — orientation: portrait checks rotation; aspect-ratio checks numeric proportion (they often overlap but differ).
• Replacing width queries — Aspect-ratio complements width breakpoints; it rarely replaces them entirely.
• Colon vs slash — Media queries use 16/9; the CSS property uses 16 / 9 with spaces.
• Ultrawide monitors — Very wide ratios may need upper bounds with max-aspect-ratio to cap layout width.

♿ Accessibility

• Content reflow — Ensure stacked portrait layouts preserve reading order and logical focus sequence.
• Zoom and resize — Users may resize windows; avoid hiding essential content at specific ratios only.
• Orientation changes — Test layout shifts when users rotate mobile devices.
• Reduced motion — Pair layout changes with prefers-reduced-motion if animations accompany ratio switches.
• Keyboard access — Layout changes must not trap focus or remove reachable controls.

💡 Best Practices