Skip to content
Tutorials Center
My learning

Topics

Lesson 8 of 39 ยท Variables, Nesting and Partials

Sass Partials and the @use Rule

Split a big stylesheet into partials and load them with @use: underscore file names, namespaces, aliases, private members, load order and why @import is deprecated.

One giant styles.scss stops being fun at around a thousand lines. Sass lets you split your code into many small files and combine them at compile time into one CSS file, so you get tidy source and a single request for the browser. The small files are called partials, and the rule that loads them is @use.

Partials: files that start with an underscore

A partial is a Sass file whose name starts with an underscore: _variables.scss, _buttons.scss. The underscore tells Sass "do not compile this into its own CSS file; it is meant to be loaded by another file". When you load it, you leave off both the underscore and the extension.

Text
styles/
  main.scss
  _variables.scss
  _buttons.scss
  components/
    _card.scss

If you run sass --watch styles:css, only main.scss becomes main.css. The partials are pulled in on demand.

Loading a file with @use

SCSS
// _variables.scss
$brand: #0ea5e9;
$radius: 6px;
SCSS
// main.scss
@use "variables";

.button {
  background: variables.$brand;
  border-radius: variables.$radius;
}

Notice three things:

  1. @use "variables" finds _variables.scss (or variables.scss, or variables/_index.scss).
  2. Everything from the loaded file is available behind a namespace, which defaults to the last part of the path. You write variables.$brand, a dot between the namespace and the variable name.
  3. @use rules must come first in the file, before any other rule (only @forward and variable declarations that configure a module may precede them).

The namespace is a feature, not a nuisance. When you see variables.$brand you know exactly where $brand came from, and two files can both define $brand without colliding.

Mixins and functions use the same dot

SCSS
@use "mixins";
@use "functions" as fn;

.card {
  @include mixins.card-shadow;
  padding: fn.rem(24px);
}

Variables keep their $: variables.$gap. Mixins and functions do not: mixins.card-shadow, fn.rem(24px).

Changing or removing the namespace

By default the namespace is the file name. You can rename it with as, which is handy for long names:

SCSS
@use "../components/design-tokens" as tokens;
.box { color: tokens.$text; }

If you use a module so often that the prefix is noise, load it with as * and drop the namespace entirely:

SCSS
@use "variables" as *;
.button { background: $brand; }

Use as * sparingly. It brings back the name-clash risk the namespaces were designed to prevent, and it hides where names come from. It is mostly sensible for your own small token or mixin files.

Private members

Names that start with a hyphen or underscore ($-internal, _helper()) are private to their file. Other files cannot see them, so a partial can have helpers without leaking them. A private variable accessed from outside is an error:

SCSS
// _theme.scss
$-base-size: 16px;               // private
$spacing: $-base-size * 2;       // public, built from the private one

Module configuration and privacy explains how to configure a module's !default variables and @forward selected parts of it.

A project you can run right here

The compiler's JavaScript API accepts custom importers, which can serve files from memory. That is how the next demo gives you a three-file project in one editor box: the strings in files play the role of _tokens.scss and _buttons.scss on disk.

A tiny multi-file project

main loads buttons, which loads tokens. Each module's CSS is included once, at the position of its first @use, no matter how many files load it. That is a big improvement over the old @import, which copied the file's CSS every time.

Folders and index files

If you point @use at a folder, Sass looks for _index.scss inside it. That makes a "barrel" file possible:

SCSS
// components/_index.scss
@forward "button";
@forward "card";
SCSS
// main.scss
@use "components";   // loads components/_index.scss

@forward re-exports modules from an index file, which is covered in Modules: @use and @forward.

Why not @import?

Older tutorials use @import "variables";. It still compiles today, but it is deprecated and will be removed in a future major version, and it has real drawbacks:

  • Everything lands in one global namespace, so names collide.
  • A file imported twice is output twice.
  • It is hard to tell where a variable came from.
  • Nothing can be private.

When you see @import in an old project, plan to move to @use. Migration and best practices in this tutorial walks through the steps, and the official sass-migrator tool automates most of the work. Note that CSS's own @import url(...) (a plain stylesheet request) is different and still works.

Where does Sass look for files?

For @use "tokens", Sass searches:

  1. The folder of the current file.
  2. Any load paths you provide with --load-path (or loadPaths), for example node_modules so you can write @use "bootstrap/scss/variables".

Compiled import order is the order of the @use rules, so list base code (tokens, functions) first and components after.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does the leading underscore in _buttons.scss mean?

    Partials are meant to be loaded by other files. Sass does not create a separate CSS output for them.
  2. 2. How do you read $brand from a file loaded with @use "variables";?

    Members live behind the module's namespace, which defaults to the file name, joined with a dot.
  3. 3. What does @use "variables" as *; do?

    as * puts the module's members in the current file's global scope. It is convenient but reintroduces possible name clashes.
  4. 4. Which names are private to a module?

    A leading hyphen or underscore makes a variable, mixin or function private. Other files cannot access it.

Summary

  • Partials start with _ and are never compiled alone; you load them without the underscore and extension.
  • @use "file" loads a module behind a namespace (file.$var, file.mixin()); as name renames it and as * removes it.
  • @use rules go first in a file, and a module's CSS is emitted only once.
  • Names starting with - or _ are private to their file.
  • @import is deprecated: prefer @use and @forward.

Next: Extend and placeholder selectors