Importing built-in modules with @use in SASS - Deep Dive

Overview - Importing built-in modules with @use

What is it?

In Sass, the @use rule lets you bring in built-in modules to use their features like functions, variables, and mixins. These built-in modules are collections of helpful tools Sass provides by default. Using @use helps keep your styles organized and avoids conflicts by giving each module its own namespace. This is a modern way to include Sass features instead of the older @import rule.

Why it matters

Without @use, stylesheets could get messy and variables or functions from different files might clash, causing bugs or unexpected results. @use solves this by clearly separating where each feature comes from, making your code easier to read and maintain. It also improves performance because Sass loads each module only once. This means your stylesheets stay clean and efficient as projects grow.

Where it fits

Before learning @use, you should understand basic Sass syntax, variables, and mixins. Knowing how @import works helps to see why @use is better. After mastering @use, you can learn about creating your own modules and using @forward to share features between files.

Mental Model

Core Idea

@use imports a built-in Sass module once and gives it a unique name to access its features safely.

Think of it like...

Imagine a toolbox with labeled compartments. Each compartment holds tools for a specific job. When you need a tool, you open the right compartment by its label, so you never mix up tools or lose them.

┌───────────────┐
│ Your Styles   │
│   ┌─────────┐ │
│   │ @use    │ │
│   │ 'sass:  │ │
│   │ module' │ │
│   └─────────┘ │
│       ↓       │
│  ┌──────────┐ │
│  │ Module   │ │
│  │ Features │ │
│  └──────────┘ │
└───────────────┘

Build-Up - 7 Steps

1

Foundation

What is @use in Sass

Concept: Introducing the @use rule as a way to include Sass modules.

The @use rule tells Sass to load a module and make its features available. Unlike @import, @use loads the module only once and keeps its variables and functions inside a namespace to avoid conflicts.

Result

You can access module features with a clear prefix, like moduleName.variable or moduleName.function().

Understanding @use is key to writing clean, maintainable Sass by avoiding naming conflicts and repeated code.

2

Foundation

Built-in Sass Modules Overview

Concept: Sass provides built-in modules with ready-to-use features.

Sass has built-in modules like sass:color, sass:list, sass:math, and sass:string. Each module offers functions and variables for common tasks, such as color manipulation or math operations.

Result

You know which built-in modules exist and what they generally provide.

Knowing built-in modules helps you avoid reinventing the wheel and speeds up your styling work.

3

Intermediate

Importing Built-in Modules with @use

🤔Before reading on: do you think you can use built-in module features directly after @use without extra setup? Commit to your answer.

Concept: How to import built-in modules using @use and access their features.

To use a built-in module, write @use 'sass:moduleName'; at the top of your Sass file. Then, access features with moduleName.featureName. For example, @use 'sass:color'; and then color.adjust($color, $amount: 10%).

Result

You can call built-in functions and use variables with the module prefix.

Understanding the namespace created by @use prevents naming collisions and clarifies where features come from.

4

Intermediate

Customizing Module Namespace with 'as'

🤔Before reading on: do you think you can rename a module's namespace when importing? Commit to yes or no.

Concept: Using the 'as' keyword to rename the module's namespace for convenience or clarity.

You can rename the module's namespace by adding 'as newName' after the module path. For example, @use 'sass:math' as m; then use m.div(10, 2). This helps shorten long names or avoid conflicts.

Result

You access module features with your chosen namespace instead of the default.

Renaming namespaces makes your code cleaner and easier to read, especially when using multiple modules.

5

Intermediate

Using Module Features in Styles

🤔Before reading on: do you think you can use built-in module functions inside property values directly? Commit to yes or no.

Concept: Applying built-in module functions and variables inside your CSS rules.

After importing a module, you can use its functions to calculate values. For example, @use 'sass:math'; .box { width: math.div(100%, 3); } This calculates one-third width using the math module.

Result

Your styles use dynamic values calculated by module functions.

Using module functions inside styles makes your CSS more powerful and adaptable.

6

Advanced

Why @use Loads Modules Only Once

🤔Before reading on: do you think @use imports the same module multiple times if used in different files? Commit to yes or no.

Concept: Understanding how Sass optimizes module loading to improve performance and consistency.

Sass loads each module only once per compilation, even if multiple files use @use for the same module. This avoids duplicated code and ensures consistent variable and function values across files.

Result

Your compiled CSS is efficient and consistent, with no repeated module code.

Knowing this prevents confusion about why changes in one file affect others using the same module.

7

Expert

Built-in Modules and Namespace Collisions

🤔Before reading on: do you think two modules can have features with the same name without conflict? Commit to yes or no.

Concept: How @use namespaces prevent conflicts even when modules have overlapping feature names.

Because @use requires a namespace, features with the same name in different modules don't clash. For example, both sass:color and sass:list might have a function named 'length', but you call them as color.length() and list.length(). This keeps your code safe and clear.

Result

You avoid bugs caused by accidentally mixing features from different modules.

Understanding namespaces is crucial for working with multiple modules and large codebases.

Under the Hood

@use tells the Sass compiler to load a module once and assign it a namespace. When you call a function or variable from that module, Sass looks it up inside the module's scope. This prevents global pollution of names and ensures that each module's features are isolated. The compiler merges all used modules and your styles into one CSS output efficiently.

Why designed this way?

The @use rule was created to fix problems with the older @import rule, which loaded files multiple times and mixed all variables and functions globally. This caused naming conflicts and slower compilation. By introducing namespaces and single loading, Sass became more reliable and maintainable.

┌───────────────┐
│ Sass File     │
│  @use 'mod';  │
│               │
│  Calls mod.fn │
└───────┬───────┘
        │
┌───────▼───────┐
│ Module Loaded │
│ Once in Cache │
│ Namespace mod │
└───────┬───────┘
        │
┌───────▼───────┐
│ Feature Lookup│
│ mod.fn() used │
└───────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does @use import the module multiple times if used in several files? Commit yes or no.

Common Belief: People often think @use imports the same module multiple times, causing duplication.

Reality: @use imports each module only once per compilation, no matter how many files use it.

Why it matters: Believing otherwise can lead to unnecessary code duplication fears and confusion about variable values.

Quick: Can you use built-in module features without the namespace prefix? Commit yes or no.

Common Belief: Some think you can call functions or variables from a module directly without the module name.

Reality: You must always use the namespace prefix unless you rename it with 'as' or use @forward with 'hide'.

Why it matters: Trying to use features without the prefix causes errors and wasted debugging time.

Quick: Does @use replace @import completely? Commit yes or no.

Common Belief: Many believe @use is just a new name for @import and works the same way.

Reality: @use is a different system with namespaces and single loading; @import is legacy and should be avoided.

Why it matters: Using @import in new projects can cause conflicts and slower builds.

Quick: Can two modules have functions with the same name without conflict? Commit yes or no.

Common Belief: People sometimes think same-named functions in different modules will clash.

Reality: Namespaces keep them separate, so no conflict occurs.

Why it matters: Misunderstanding this limits use of multiple modules and causes unnecessary renaming.

Expert Zone

1

Built-in modules sometimes share similar function names but behave differently; knowing their exact behavior avoids subtle bugs.

2

The 'as *' syntax can import a module without a namespace, but this risks name collisions and is discouraged in large projects.

3

Some built-in modules have configuration options that can be set only once per compilation, affecting all files using them.

When NOT to use

Avoid using @use when you need to import plain CSS files or third-party CSS libraries; use @import or link tags instead. Also, for legacy Sass codebases heavily relying on global variables, migrating to @use requires careful refactoring.

Production Patterns

In production, teams use @use to import built-in modules like sass:color and sass:math for consistent styling utilities. They often alias namespaces for brevity and combine @use with @forward to create shared design systems and component libraries.

Connections

JavaScript ES6 Modules

Both use explicit imports with namespaces to avoid global conflicts.

Understanding how @use namespaces work is similar to how JavaScript imports modules, helping developers manage code dependencies cleanly.

Unix Shell Environment Variables

Both isolate settings or variables in separate namespaces to prevent conflicts.

Knowing how environment variables are scoped in shells helps grasp why Sass uses namespaces to keep modules separate.

Library Organization in a Physical Library

Modules are like sections in a library, each with its own books (features), accessed by section name.

This connection shows how organizing code into modules helps find and use features efficiently without confusion.

Common Pitfalls

#1 Trying to use a built-in module feature without the namespace prefix.

Wrong approach:

.box { width: div(100%, 3); }

Correct approach:

@use 'sass:math'; .box { width: math.div(100%, 3); }

Root cause:

Not understanding that @use creates a namespace that must prefix all module features.

#2 Using @import to load built-in Sass modules instead of @use.

Wrong approach:

@import 'sass:color'; .text { color: adjust($color, $amount: 10%); }

Correct approach:

@use 'sass:color'; .text { color: color.adjust($color, $amount: 10%); }

Root cause:

Confusing legacy @import with modern @use syntax and capabilities.

#3 Importing the same built-in module multiple times with different namespaces unnecessarily.

Wrong approach:

@use 'sass:math' as m1; @use 'sass:math' as m2; .a { width: m1.div(10, 2); } .b { width: m2.div(20, 4); }

Correct approach:

@use 'sass:math' as math; .a { width: math.div(10, 2); } .b { width: math.div(20, 4); }

Root cause:

Not realizing Sass loads each module once and multiple namespaces for the same module are redundant and confusing.

Key Takeaways

@use is the modern way to import built-in Sass modules, providing namespaces to avoid conflicts.

Built-in modules like sass:color and sass:math offer powerful functions and variables to simplify styling tasks.

Always use the module's namespace prefix to access its features unless you rename it with 'as'.

@use loads each module only once per compilation, improving performance and consistency.

Avoid using legacy @import for Sass modules; prefer @use for cleaner, safer, and more maintainable code.

Practice

1. What does the Sass @use rule do when importing built-in modules?

easy

A. It imports CSS files directly into Sass without any namespace.

B. It imports a built-in Sass module to use its features with a namespace.

C. It compiles Sass files into CSS automatically.

D. It removes unused CSS rules from the stylesheet.

Solution

1. Step 1: Understand the purpose of @use

   The @use rule imports Sass modules and gives access to their functions and variables under a namespace.

2. Step 2: Differentiate from other Sass features

   Unlike @import, @use does not import raw CSS but Sass modules with scoped namespaces.

3. Final Answer:

   It imports a built-in Sass module to use its features with a namespace. -> Option B

4. Quick Check:

   @use imports modules with namespace [OK]

Hint: Remember: @use always adds a namespace to imported modules [OK]

Common Mistakes:

• Confusing @use with @import for CSS files
• Thinking @use compiles Sass to CSS
• Assuming @use removes unused CSS

2. Which of the following is the correct syntax to import the built-in Sass math module using @use?

easy

A. @use "math";

B. @import "sass:math";

C. @use "sass:math";

D. @use math;

Solution

1. Step 1: Recall the correct syntax for built-in modules

   Built-in Sass modules are imported with @use "sass:module-name"; syntax.

2. Step 2: Check each option

   @use "sass:math"; uses the correct syntax with quotes and the prefix sass:. Others miss quotes, prefix, or use @import.

3. Final Answer:

   @use "sass:math"; -> Option C

4. Quick Check:

   Built-in modules need @use "sass:module"; [OK]

Hint: Built-in modules always use "sass:" prefix inside quotes [OK]

Common Mistakes:

• Omitting quotes around module name
• Using @import instead of @use
• Forgetting the "sass:" prefix

3. Given the Sass code:

@use "sass:color";

.my-text {
  color: color.scale(color.$blue, $lightness: 20%);
}

What color effect does this code apply to .my-text?

medium

A. It causes a syntax error.

B. It makes the blue color 20% darker.

C. It changes the blue color to red.

D. It makes the blue color 20% lighter.

Solution

1. Step 1: Understand color.scale function

   The color.scale function adjusts color properties like lightness by the given percentage.

2. Step 2: Analyze the argument $lightness: 20%

   This increases the lightness of the blue color by 20%, making it lighter.

3. Final Answer:

   It makes the blue color 20% lighter. -> Option D

4. Quick Check:

   color.scale with positive lightness increases brightness [OK]

Hint: Positive $lightness in color.scale makes color lighter [OK]

Common Mistakes:

• Confusing lightness increase with darkening
• Assuming color changes hue instead
• Thinking the code has syntax errors

4. What is wrong with this Sass code snippet?

@use "sass:math";

.box {
  width: math.percentage(0.5);
}

medium

A. The math.percentage() function does not exist; it should be math.percent().

B. The @use statement is missing a semicolon.

C. The function name should be math.percent() instead of math.percentage().

D. There is no error; the code is correct.

Solution

1. Step 1: Check the function name in the math module

   The correct function to convert a decimal to a percentage is math.percent(), not math.percentage().

2. Step 2: Verify the rest of the code

   The @use statement is correct and has a semicolon; only the function name is wrong.

3. Final Answer:

   The math.percentage() function does not exist; it should be math.percent(). -> Option A

4. Quick Check:

   Use math.percent() for percentage conversion [OK]

Hint: Remember: math.percent(), not math.percentage() [OK]

Common Mistakes:

• Using incorrect function name math.percentage()
• Thinking @use needs no semicolon
• Assuming code is error-free

5. You want to use the Sass math module to calculate the width as 75% of 1200px. Which code correctly imports the module and calculates the width?

hard

A. @use "sass:math";
.container {
width: math.div(75, 100) * 1200px;
}

B. @use "sass:math";
.container {
width: math.percent(0.75);
}

C. @use "sass:math";
.container {
width: math.div(75%, 100) * 1200px;
}

D. @use "sass:math";
.container {
width: math.percent(75) * 1200px;
}

Solution

1. Step 1: Import the math module correctly

   The code uses @use "sass:math"; which is correct for built-in modules.

2. Step 2: Calculate 75% of 1200px correctly

   Using math.div(75, 100) divides 75 by 100 to get 0.75, then multiplies by 1200px for the width.

3. Step 3: Check other options for errors

   @use "sass:math"; .container { width: math.percent(0.75); } sets width to 75% of the parent, not a fixed 900px. @use "sass:math"; .container { width: math.div(75%, 100) * 1200px; } uses math.div(75%, 100) which equals 0.75% (dividing percentage by unitless keeps %), so 0.75% * 1200px = 9px. @use "sass:math"; .container { width: math.percent(75) * 1200px; } uses math.percent(75) which returns 7500%.

4. Final Answer:

   @use "sass:math"; .container { width: math.div(75, 100) * 1200px; } -> Option A

5. Quick Check:

   Use math.div for division, multiply for percentage calculation [OK]

Hint: Use math.div(percentage, 100) to get decimal for calculations [OK]

Common Mistakes:

• Using math.percent() for relative percentage instead of fixed pixel calculation
• Dividing percentages by unitless numbers (keeping % unit)
• Misunderstanding multiplication with units