Skip to content
Tutorials Center
My learning

Topics

Lesson 26 of 39 ยท Real-world Patterns

A Responsive Breakpoint System in Sass

Create a reusable Sass breakpoint system: a breakpoints map, up, down and between mixins, container-query helpers, fluid sizing and safe error messages for unknown names.

Media queries scattered through a stylesheet as @media (min-width: 768px) have two problems. The numbers repeat (and drift: 768 here, 770 there), and the intent is hidden, because nobody remembers what 768 means. A breakpoint system gives each width a name and wraps the query in a mixin, so the code reads @include up(md) and every file agrees on where "medium" starts.

You will build the system from the pieces covered earlier: maps, mixins with @content, and @error.

The breakpoints map

SCSS
$breakpoints: (
  sm: 40rem,   // 640px
  md: 48rem,   // 768px
  lg: 64rem,   // 1024px
  xl: 80rem,   // 1280px
);

Use rem so queries respect a user's larger default font size (browsers resolve rem in media queries against the initial font size, so zooming text behaves well). Do not tie breakpoints to devices ("iPad"). Choose widths where your content starts to break.

Mobile first with up()

Write the base styles for small screens with no media query, then add rules that apply from a width upward. This is called mobile first, and it needs only min-width queries:

SCSS
@use "sass:map";

@mixin up($name) {
  $width: map.get($breakpoints, $name);
  @if not $width {
    @error "Unknown breakpoint `#{$name}`. Use one of: #{map.keys($breakpoints)}";
  }
  @media (min-width: $width) {
    @content;
  }
}

@content is the block the caller passes in. Using it:

SCSS
.layout {
  display: grid;
  gap: 1rem;

  @include up(md) {
    grid-template-columns: 1fr 2fr;
  }
}

Because @include is inside .layout, Sass nests the media query and bubbles it up: the output is @media (min-width: 48rem) { .layout { grid-template-columns: 1fr 2fr; } }. The rule stays next to the component it belongs to. That locality is the main reason to write queries with a mixin rather than collecting them at the bottom of the file.

down() and between()

Sometimes you need styles only below a width. Subtract a tiny amount from the next breakpoint so the ranges never overlap at the exact boundary:

SCSS
@mixin down($name) {
  $width: map.get($breakpoints, $name);
  @if not $width { @error "Unknown breakpoint `#{$name}`."; }
  @media (max-width: $width - 0.0625rem) { @content; }   // 1px below
}

@mixin between($low, $high) {
  @include up($low) {
    @include down($high) { @content; }
  }
}

Nesting up inside down combines the two queries into one: @media (min-width: 40rem) and (max-width: 47.9375rem). Sass merges nested @media rules automatically.

up, down and between

Drag the pane or the window wider and narrower (the test widths here are small on purpose) and watch the ::after text change. Read the compiled CSS to see how between merged the two conditions.

Reusing the map for other tools

Because breakpoints are data, other code can read them. Generate custom properties for JavaScript:

SCSS
:root {
  @each $name, $width in $breakpoints {
    --bp-#{$name}: #{$width};
  }
}

Or build responsive utility variants from the same map (see utility class generators). One source of truth means no mismatch between CSS and JS.

Container queries

Viewport breakpoints describe the window, but a reusable component cares about the size of its container. CSS container queries solve this and slot neatly into the same pattern:

SCSS
$containers: (sm: 20rem, md: 30rem, lg: 45rem);

@mixin container-up($name) {
  @container (min-width: #{map.get($containers, $name)}) {
    @content;
  }
}

.card-wrapper { container-type: inline-size; }

.card {
  display: block;
  @include container-up(md) {
    display: grid;
    grid-template-columns: 8rem 1fr;
  }
}

Use viewport breakpoints for page layout (columns, navigation) and container queries for components (a card that is horizontal when it has room).

Interpolation in media queries

Since Sass 3.x you can use variables directly in media features, as the mixins above do. You may also build whole queries as strings with interpolation:

SCSS
$print: "print";
$retina: "(min-resolution: 2dppx)";

@media #{$print} and #{$retina} { ... }

Prefers-queries are common companions to breakpoints and benefit from mixins too:

SCSS
@mixin reduced-motion {
  @media (prefers-reduced-motion: reduce) { @content; }
}

.hero { animation: slide 600ms ease-out; @include reduced-motion { animation: none; } }
A reduced-motion and dark-mode helper

Fluid values instead of more breakpoints

Every breakpoint adds CSS to maintain. For sizes that should scale smoothly, use clamp() and a function that calculates the preferred value, so the design adapts continuously between two widths:

SCSS
@use "sass:math";

@function fluid($min, $max, $from: 320, $to: 1280) {
  $slope: math.div($max - $min, $to - $from);
  $intercept: $min - $slope * $from;
  @return clamp(#{$min * 1px}, #{$intercept * 1px} + #{$slope * 100}vw, #{$max * 1px});
}

h1 { font-size: fluid(28, 56); }

At or below 320px the heading is 28px, at or above 1280px it is 56px, and in between it grows linearly. Keep breakpoints for structure changes and fluid values for sizes.

Common mistakes

  • Mixing min-width and max-width styles for the same property, creating overlapping ranges that are hard to reason about. Pick mobile first and stick to up().
  • Using the same pixel value in up and down. max-width: 768px and min-width: 768px both match at exactly 768px. Subtract a small amount.
  • Too many breakpoints. Three or four named widths are enough for most sites.
  • Hard-coding widths inside components. Always go through the mixin so changes happen in one place.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What does @content do inside a mixin?

    @content marks where the block that follows @include is placed.
  2. 2. Why use max-width: $width - 0.0625rem in a down() mixin?

    Subtracting 1px leaves no overlap at the exact breakpoint.
  3. 3. What does mobile first mean in this system?

    Start with the smallest layout and enhance upward with up().
  4. 4. When do container queries beat viewport media queries?

    A component's layout should depend on its container, not on the window.
  5. 5. What happens if two nested @media rules come from up() inside down()?

    Sass merges nested media queries with and.

Summary

  • Name your breakpoints in a map and wrap queries in up(), down() and between() mixins.
  • Write mobile first with min-width; subtract a small amount in down() to avoid overlap.
  • @content plus nesting keeps each query next to the component it changes, and Sass merges nested queries.
  • Validate names with @error; reuse the map for custom properties and utilities.
  • Use container-query mixins for components, clamp() with a fluid() function for smooth sizes.

Next: BEM and Component Patterns