SASS @use Rule - Load, Find, And Configure SCSS Modules

1. What is @use Rule in SASS?

The @use rule works more or less identically to the @import directive in the SASS language. It loads the mixins, functions, variables, and CSS style declarations from other stylesheets. Further, the stylesheets loaded by the SCSS @use rule are acknowledged as modules.

In this tutorial, we will explore the SCSS @use directive, its syntax, and usage with examples. In addition, we will talk about the method to load the members of the stylesheets via the SASS @use directive and further, how to configure the modules after loading them. Further, we will learn how to find files with this @use directive. Besides, we will also cover the differences from the SASS @import rule in this chapter.

1.1. Syntax of SCSS @use Rule

LIke other at-rules in SASS programming, the syntax of the @use directive is straight forward.

@use "ulr-of-the-file";

• The syntax has two parts.
• The directive @use itself.
• URL of the stylesheet which this directive embraces.
• After including this directive, the modules will be loaded into the compiled CSS once, even if those modules are added earlier many times.

2. How to Utilize the @use Directive?

There are certain requirements to add this @use rule in SCSS stylesheets.

• This rule must be written at the top of the stylesheet in which modules are added.
• However, the SASS @forward directive comes before this rule.
• Also, we can declare the variables before this @use directive.
• But we must not include any other SCSS at-rule before this directive, other than the aforementioned modules.
• Moreover, we do not append the extension .scss while adding a file with the @use rule.

Examine the below instance in which we made a file src/_base.scss and included this file into the style.scss by exerting the @use directive.

p, h1, h2, h3, h4, h5, h6 {
	font-family: 'Roboto Slab', sans-serif;
	color: #333;
}

@use 'src/base';

3. Load the Members Via @use SCSS Rule

The SASS language has very interesting features for us. It means we can load the modules of other SCSS stylesheets using the @use directive. Further, we can access those SCSS variables, SASS mixins, and functions with the help of namespace.

3.1. What is namespace in SASS?

A namespace is the last component or part of the file's URL. When we add the file with the @use rule, we access the modules by incorporating a namespace. Hence, the namespace will only target the modules of that specific file. Below is the method to load the modules by namespace.

namespace.variable-name;
namespace.function-name();
@include namespace.mixin-name();

3.2. Load Modules With Namespace

Let us understand the namespace handling to include the modules by the following example.

$color: #2a73cc;
@mixin theme{
	border: 5px solid $color;
}

@use "src/main";
ul.lead{
	@include main.theme;
	background: rgb(main.$color, 0.2);
	color: main.$color;
}

ul.lead {
	border: 5px solid #2a73cc;
	background: rgba(42, 115, 204, 0.2);
	color: #2a73cc;
}

3.3. How to Choose Namespace?

• By default, the namespace is the last part of the URL of the file excluding the extension .scss.
• However, the SCSS provides us with the facility to choose our specific namespace.
• In this way, we can choose a shorter or easy-to-reference namespace.
• This namespace can be any string or a character.
• Usage @use 'url-of-the-file' as choose-your-namespace;.

Let us comprehend the concept to choose our namespace with an example.

$color: #2a73cc;
$font: 16px;
$font-family: 'Roboto', sans-serif;
@mixin border{
	border: 10px solid $color;
}

@use "src/base" as b;
.main-wrapper{
	@include b.border;
	background: rgb(b.$color, 0.2);
	color: b.$color;
	font-family: b.$font-family;
	font-size: b.$font;
}

.main-wrapper{
	border: 10px solid #2a73cc;
	background: rgba(42, 115, 204, 0.2);
	color: #2a73cc;
	font-family: 'Roboto', sans-serif;
	font-size: 16px;
}

3.4. Load Modules Without Namespace

Apart from adding the modules with namespaces, we can even load them without namespaces. However, it is endorsed only if the stylesheets are drafted by yourself. We include the modules without namespace by @use 'file-path' as *. Let us apprehend this with an example.

$color: #2a73cc;
$background: #f8f9fa;

@use "src/base" as *;
a{
	color: $color;
	background: $background;
}

a{
	color: #2a73cc;
	background: #f8f9fa;
}

3.5. What Are Private Members in SASS?

• Sometimes, while you write SCSS stylesheets, you do not want to load all the members of that file when included with the @use rule.
• In that case, we make the members of the file private while declaring them.
• To make a SASS variable private, we add a dash - or underscore _ as a prefix.
• The working of these variables will be totally fine within the stylesheet.
• However, while loading that file with the @use directive, the private SCSS members won't be part of it.
• Hence, the underscore _ or dash - make the members hidden.

Check the underneath instance to understand this notion.

$-radius: 5px;
@mixin edges{
	border-radius: $-radius;
}

@use "src/core";
.wrapper{
	@include core.edges;

	// However, loading the $-radius will cause error
	padding: core.$-radius;
}

4. Configure SASS Modules With @use Rule

• Sometimes, we want to load the SCSS variables of a stylesheet with our configuration while encompassing the @use rule.
• To do so, we add a !default flag after the value of the variable in the file which is to be loaded.
• Hence, the variable is now available to add our configuration while loading that file.
• Further, to configure the variable value, we use the with keyword after the URL of the file.
• After that, we can define our configuration within the parenthesis.
• Usage @use "file-url" with (var: value, var: valeu, ...);.

$font: 'Noto Sans', sans-serif !default;
$background: #f8f9fa !default;
body{
	font-family: $font;
	background: $background;
	padding: 30px;
}

@use "src/base" with (
	$font: 'Roboto', sans-serif,
	$background: #ffffff
);

body{
	font-family: 'Roboto', sans-serif;
	background: #ffffff;
	padding: 30px;
}

4.1. Configure Variables Via SASS Mixins

• Configuring the SASS variables by employing the @use "file-path" with (...); is a very useful method.
• This method is very handy while working with the SCSS libraries which were originally written to work with the @import directive.
• However, this technique is not encouraged always especially in advanced cases due to a lack of flexibility.
• To configure many variables, configure them after loading that stylesheet.
• For this purpose, write a mixin to configure variables and define another one to include them in the stylesheet.

Let us understand the above concept of how to configure the SASS variables with the help of a mixin by an example.

$-black: #000;
$-border-radius: 5px;
$-box-shadow: null;

// Returns a value, if the user configures "$-box-shadow"
// Else returns a value computer from "$-black"
@function -box-shadow(){
	@return $-box-shadow or (0 0 5px rgba($-black, 0.2));
}
@mixin configure($black: null, $border-radius: null, $box-shadow: null){
	@if $black{
		$-black: $black !global;
	}
	@if $border-radius{
		$-border-radius: $border-radius !global;
	}
	@if $box-shadow{
		$-box-shadow: $box-shadow !global;
	}
}
@mixin generate{
	.wrapper{
		border-radius: $-border-radius;
		box-shadow: -box-shadow();
	}
}

@use "src/library";
@include library.configure(
	$black: #333,
	$border-radius: 10px
);
@include library.generate;

.wrapper{
	border-radius: 10px;
	box-shadow: 0 0 5px rgba(51, 51, 51, 0.2);
}

4.2. Explanation

• In the above instance, we utilized the SASS @function rule to form a -box-shadow() function.
• This function computes and returns the box-shadow according to the variable $-black.
• Further, we employed the @mixin directive to create a mixin configure.
• This SASS mixin is used to configure the values of the variables after we load the file with the @use rule.
• Notice the !global flag, which allows us to declare these variables again, even though they are already defined earlier.
• Moreover, We formulated a mixin generate to get the computed CSS results.
• After loading the SASS stylesheet with the @use directive, we set the new values of the variables by the configure mixin.
• Hence, the new values of the variables override the previously declared values.
• Finally, we got the computed CSS with the mixin generate.

4.3. Reassign Variable Values

We can also reassign the variables of a file, after including it in our current stylesheet. We simply do this by assigning new values and hence, the old values will be overridden.

$color: #333;

@use "main";
main.$color: #2a73cc;

5. Finding Modules With @use Directive

• While loading files with the @use rule, it is not recommended to write absolute file names for every SASS stylesheet.
• SASS algorithm makes it very easy to find the modules.
• For example, we do not have to write the extension of the file i.e. @use 'base' will automatically load the base.scss, base.sass, or base.css.
• Moreover, we do add the stylesheets by file URL with the forward slashes and avoid file paths with the backward slashes.
• In this way, the file will work on every operating system.
• Finding SCSS modules in the @use rule is similar to loading variables in the @import directive.

There are three approaches to finding modules via the @use rule.

1. Load Paths
2. SASS Partials
3. Index Files

5.1. Load Paths

• In every SCSS implementation, there is this functionality to load the paths of files.
• Once, the path is added, the modules will then be loaded concerning that specified path.
• Hence, there will be no need to write the complete URL every time.
• For example, if we pass the src/main/base/sass as the load path, we can then load the modules as @use 'variables', @use 'library', etc.
• This will include the stylesheet at src/main/base/sass/variables.scss and src/main/base/sass/library.scss respectively.
• Moreover, SCSS does not incorporate the / for relative imports, because relative imports are always accessible.
• Further, we only utilize the load path method when there is no relative file that matches the module URL.

5.2. SASS Partials

• SCSS partials are a special and unique type of stylesheet.
• These files are created for loading the modules only.
• Further, the SASS partials are not compiled or transpiled on their own.
• There is an underscore _ as a prefix in partials like _lists.scss.
• However, we do not add the underscore _ while loading the file with the @use directive like @use 'list'.

5.3. Index Files

The index file is another method to load the modules in the SCSS language. If we write a file _index.scss or _index.sass in a folder named library, this index file will automatically load upon including the URL of that folder. Besides adding this index file, any modules or stylesheets loaded inside it will also be loaded. Let us discern this concept with an instance.

.main-wrapper{
	padding: 20px;
	margin: 0;
	border-radius: 5px;
	background: #f8f9fa;
}

ul{
	margin-left: 10px;
	font-size: 14px;
	padding: 10px;
}
ul a{
	color: red;
}

@use 'main';
@use 'list';

@use 'index';

.main-wrapper{
	padding: 20px;
	margin: 0;
	border-radius: 5px;
	background: #f8f9fa;
}
ul{
	margin-left: 10px;
	font-size: 14px;
	padding: 10px;
}
ul a{
	color: red;
}

6. Loading CSS Files Using @use Rule

• Since we loaded the .scss or .sass files previously by utilizing the @use rule.
• However, we can load plain CSS stylesheets with this directive also.
• The method is similar to loading the SCSS files.
• But loading CSS files with this rule does not allow any special SASS features.
• Importantly, do not write any SASS code in .css files.
• Otherwise, loading the CSS file containing SCSS modules will produce an error.
• Therefore, we must write only CSS declarations in our CSS stylesheets.
• Further, these CSS files can also be extended via the @extend rule.

.wrapper{
	display: block;
	padding: 20px;
	margin: 0;
	font-size: 16px;
}

@use 'src/content';

.wrapper{
	display: block;
	padding: 20px;
	margin: 0;
	font-size: 16px;
}

7. Differences Between SASS @use and @import Rule

There are some differences between the SCSS @use rule and the @import directive. The following list contains all the possible differences between the two at-rules. Originally, the @use directive was designed to replace the SCSS @import rule, however, it operates slightly differently from it.