The SCSS file (.scss, .sass)

The basics

What is an SCSS file?

Anatomy

What's inside an SCSS file

SCSS looks like CSS with extra powers: anything you can write in a .css file works, and on top of that come variables, nesting, mixins, functions and modules. Here is a small partial, part by part. It assumes a _tokens.scss file next to it that defines $brand.

// _buttons.scss: button styles
@use "sass:color";
@use "tokens" as t;

$padding: 0.5rem 1rem !default;

@mixin focus-ring($c: t.$brand) {
  outline: 3px solid $c;
}

/* Buttons */
.button {
  padding: $padding;
  background: t.$brand;

  &:hover {
    background: color.scale(t.$brand, $lightness: -15%);
  }

  &--large {
    font-size: 1.25rem;
  }

  &:focus-visible {
    @include focus-ring;
  }
}

1. 1// _buttons.scss: button styles

   A silent comment

   Comments with // are for the people editing the file and never reach the CSS. The leading underscore in the file name makes this a partial: Sass won't compile it on its own, only as part of a file that loads it.

2. 2@use "sass:color";

   A built-in module

   Sass's own functions come in modules such as sass:color, sass:math and sass:map. After this line, colour functions are called as color.scale(), color.adjust() and so on.

3. 3@use "tokens" as t;

   Loading another file

   Loads _tokens.scss from the same folder, once, under the namespace t. You leave out the underscore and the extension. @use rules must come before any style rules.

4. 4$padding: 0.5rem 1rem !default;

   A variable

   Sass variables start with $. !default means "use this unless the file loading me set it already", which is how libraries let you configure them.

5. 5@mixin focus-ring($c: t.$brand) { … }

   A mixin

   A reusable block of declarations with an optional parameter and a default value. It produces nothing until it's included somewhere.

6. 6/* Buttons */

   A loud comment

   A normal CSS comment. Sass copies it into the output, except in compressed mode. Start it with /*! to keep it even then, for licence notices.

7. 7t.$brand

   A member of another module

   The variable $brand from _tokens.scss, reached through its namespace. With @use, nothing becomes global, so you always know where a name comes from.

8. 8&:hover { … }

   Nesting and the parent selector

   A rule inside a rule. & stands for the outer selector, so this compiles to .button:hover.

9. 9color.scale(t.$brand, $lightness: -15%)

   A function call

   Runs while compiling and outputs a plain colour. The browser never sees the function, only the result.

10. 10&--large { … }

    Building a class name

    &--large becomes .button--large, the BEM naming style. This is one thing native CSS nesting can't do: there, & can't be glued to the rest of a class name.

11. 11@include focus-ring;

    Using the mixin

    Copies the mixin's declarations here, with the default parameter.

How it's used

How an SCSS file becomes CSS

/* Buttons */
.button {
  padding: 0.5rem 1rem;
  background: #046eff;
}
.button:hover {
  background: rgb(0%, 36.4594953519%, 86.3333333333%);
}
.button--large {
  font-size: 1.25rem;
}
.button:focus-visible {
  outline: 3px solid #046eff;
}

Versions

@use, @forward and the end of @import

// styles/_index.scss: one entry point for a folder of partials
@forward "tokens";
@forward "mixins";

// main.scss
@use "styles";        // loads styles/_index.scss
.card { color: styles.$brand; }

File conventions

Partials, encoding and comments

Comparison

SCSS vs Less vs plain CSS

Troubleshooting

Why won't my SCSS compile?

How to

How to open, edit and convert an SCSS file

Security

What SCSS can reveal, and compiling other people's Sass

Free downloads

Sample SCSS files to download

Free sample Sass files for testing compilers, build pipelines, editors and syntax highlighters. Every file compiles without errors or warnings in Dart Sass 1.106.1.

Loading…

What's inside sample-styles.scss

The file is commented: open it in a text editor and each numbered comment marks one of these parts. sample-styles.css is what Dart Sass makes of it.

1. Comment 1: built-in modules

   @use loads sass:color, sass:map and sass:math, so the rest of the file calls color.scale(), map.get() and math.div().

2. Comments 2 to 4: variables, a map and a function

   $brand and $radius with !default, a map of breakpoints, and a rem() function that converts pixels to rem with math.div().

3. Comments 5 and 6: a mixin and a placeholder

   above("md") wraps its content in a media query and stops the compile with @error for an unknown breakpoint. %focus-ring only appears in the CSS because .button:focus-visible extends it, at the placeholder's position, which is why that rule comes first in the output.

4. Comment 7: Sass variables into custom properties

   --brand: #{$brand}; writes a compile-time value into a CSS variable that stays live in the browser.

5. Comments 8 and 9: nesting and colour functions

   A .card with nested h2, &:hover, &--featured and a media query that bubbles up, and a .button whose hover colour is computed with color.scale().

6. Comments 10 and 11: loops

   @each turns a map into three .badge-* classes, and @for writes .mt-1 to .mt-4.

7. Comment 12: non-ASCII output

   A € in a content string makes Dart Sass start the CSS with @charset "UTF-8";.

All sample SCSS files

• Commented SCSS stylesheet

  sample-styles.scss · 2.9 KB (2,994 bytes)

  A self-contained stylesheet that uses built-in modules, variables, a map, a function, a mixin with @content, a placeholder with @extend, nesting, @each and @for, with 12 numbered comments.

  • Testing Sass compilers and build pipelines
  • Teaching the parts of an SCSS file
  DownloadOpen

• Compiled CSS of the featured sample

  sample-styles.css · 1.2 KB (1,258 bytes)

  The output of npx sass --no-source-map sample-styles.scss sample-styles.css with Dart Sass 1.106.1. It passes the CSSTree validator.

  • Comparing your compiler's output
  • Seeing what each Sass feature turns into
  DownloadOpen

• Partial with variables, a function and a mixin

  _sample-tokens.scss · 770 bytes

  A partial (leading underscore) with !default variables, a private $-ratio and a function and mixin for other files to use. Download it together with sample-main.scss.

  • Testing that tools skip partials
  • Testing `@use … with (…)` configuration
  DownloadOpen

• Entry file that loads the partial with @use

  sample-main.scss · 957 bytes

  Loads _sample-tokens.scss with @use "sample-tokens" as tokens with (…), overriding two defaults, and uses its members through the namespace. Put both files in the same folder to compile it.

  • Testing module resolution and load paths
  • Checking a migration from `@import` to `@use`
  DownloadOpen

• Indented syntax (.sass)

  sample-indented.sass · 849 bytes

  The same kinds of rules in Sass's original syntax: no braces or semicolons, with indentation for nesting and a mixin with a parameter.

  • Testing `.sass` support in compilers and editors
  • Comparing the two Sass syntaxes
  DownloadOpen

• UTF-8 with BOM and CRLF line endings

  sample-windows.scss · 800 bytes

  Saved with a UTF-8 byte order mark and Windows line endings, with text in eight scripts, emoji, a .café class and a \20AC escape.

  • Checking tools that choke on a BOM or CRLF
  • Spotting encoding bugs in the CSS output
  DownloadOpen

Ways to test with them

• Compiler output: compile sample-styles.scss with your setup and compare it with sample-styles.css. Older compilers differ in colour formatting; LibSass rejects @use altogether.
• Partials and load paths: compile the folder with sass .:out. _sample-tokens.scss should be skipped, and sample-main.scss should find it.
• Encoding: compile sample-windows.scss. The CSS should start with @charset "UTF-8"; and show the text unchanged; any Ã or â€ means a step misread UTF-8.
• Syntax support: an editor or highlighter that handles .scss but not .sass will show sample-indented.sass as plain text.

Free to use for testing, teaching and demos, commercially or not, with no attribution needed. A link back to this page is always appreciated.

Questions

SCSS files, frequently asked