--- title: "@use" table_of_contents: true introduction: > The `@use` rule loads [mixins](mixin), [functions](function), and [variables](../variables) from other Sass stylesheets, and combines CSS from multiple stylesheets together. Stylesheets loaded by `@use` are called "modules". Sass also provides [built-in modules](../modules) full of useful functions. --- <% content_for :before_introduction do %> <%= partial '../snippets/module-system-status' %> <% end %> The simplest `@use` rule is written `@use ""`, which loads the module at the given URL. Any styles loaded this way will be included exactly once in the compiled CSS output, no matter how many times those styles are loaded. <% heads_up do %> A stylesheet's `@use` rules must come before any rules other than `@forward`, including [style rules][]. However, you can declare variables before `@use` rules to use when [configuring modules][]. [style rules]: ../style-rules [configuring modules]: #configuring-modules <% end %> <% example do %> // foundation/_code.scss code { padding: .25em; line-height: 0; } --- // foundation/_lists.scss ul, ol { text-align: left; & & { padding: { bottom: 0; left: 0; } } } --- // style.scss @use 'foundation/code'; @use 'foundation/lists'; === // foundation/_code.sass code padding: .25em line-height: 0 --- // foundation/_lists.sass ul, ol text-align: left & & padding: bottom: 0 left: 0 --- // style.sass @use 'foundation/code' @use 'foundation/lists' === code { padding: .25em; line-height: 0; } ul, ol { text-align: left; } ul ul, ol ol { padding-bottom: 0; padding-left: 0; } <% end %> ## Loading Members You can access variables, functions, and mixins from another module by writing `.`, `.()`, or `@include .()`. By default, the namespace is just the last component of the module's URL. Members (variables, functions, and mixins) loaded with `@use` are only visible in the stylesheet that loads them. Other stylesheets will need to write their own `@use` rules if they also want to access them. This helps make it easy to figure out exactly where each member is coming from. If you want to load members from many files at once, you can use the [`@forward` rule][] to forward them all from one shared file. [`@forward` rule]: forward <% fun_fact do %> Because `@use` adds namespaces to member names, it's safe to choose very simple names like `$radius` or `$width` when writing a stylesheet. This is different from the old [`@import` rule][], which encouraged that users write long names like `$mat-corner-radius` to avoid conflicts with other libraries, and it helps keep your stylesheets clear and easy to read! [`@import` rule]: import <% end %> <% example do %> // src/_corners.scss $radius: 3px; @mixin rounded { border-radius: $radius; } --- // style.scss @use "src/corners"; .button { @include corners.rounded; padding: 5px + corners.$radius; } === // src/_corners.sass $radius: 3px @mixin rounded border-radius: $radius --- // style.sass @use "src/corners" .button @include corners.rounded padding: 5px + corners.$radius === .button { border-radius: 3px; padding: 8px; } <% end %> ### Choosing a Namespace By default, a module's namespace is just the last component of its URL without a file extension. However, sometimes you might want to choose a different namespace—you might want to use a shorter name for a module you refer to a lot, or you might be loading multiple modules with the same filename. You can do this by writing `@use "" as `. <% example do %> // src/_corners.scss $radius: 3px; @mixin rounded { border-radius: $radius; } --- // style.scss @use "src/corners" as c; .button { @include c.rounded; padding: 5px + c.$radius; } === // src/_corners.sass $radius: 3px @mixin rounded border-radius: $radius --- // style.sass @use "src/corners" as c .button @include c.rounded padding: 5px + c.$radius === .button { border-radius: 3px; padding: 8px; } <% end %> You can even load a module *without* a namespace by writing `@use "" as *`. We recommend you only do this for stylesheets written by you, though; otherwise, they may introduce new members that cause name conflicts! <% example do %> // src/_corners.scss $radius: 3px; @mixin rounded { border-radius: $radius; } --- // style.scss @use "src/corners" as *; .button { @include rounded; padding: 5px + $radius; } === // src/_corners.sass $radius: 3px @mixin rounded border-radius: $radius --- // style.sass @use "src/corners" as * .button @include rounded padding: 5px + $radius === .button { border-radius: 3px; padding: 8px; } <% end %> ### Private Members As a stylesheet author, you may not want all the members you define to be available outside your stylesheet. Sass makes it easy to define a private member by starting its name with either `-` or `_`. These members will work just like normal within the stylesheet that defines them, but they won't be part of a module's public API. That means stylesheets that load your module can't see them! <% fun_fact do %> If you want to make a member private to an entire *package* rather than just a single module, just don't [forward its module][] from any of your package's entrypoints (the stylesheets you tell your users to load to use your package). You can even [hide that member][] while forwarding the rest of its module! [forward its module]: forward [hide that member]: forward#controlling-visibility <% end %> <% example(autogen_css: false) do %> // src/_corners.scss $-radius: 3px; @mixin rounded { border-radius: $-radius; } --- // style.scss @use "src/corners"; .button { @include corners.rounded; // This is an error! $-radius isn't visible outside of `_corners.scss`. padding: 5px + corners.$-radius; } === // src/_corners.sass $-radius: 3px @mixin rounded border-radius: $radius --- // style.sass @use "src/corners" .button @include corners.rounded // This is an error! $-radius isn't visible outside of `_corners.scss`. padding: 5px + corners.$-radius <% end %> ## Configuring Modules A stylesheet can define variables with the [`!default` flag][] to make them configurable. To load a module with configuration, write `@use with (: , : )`. The configured values will override the variables' default values. [`!default` flag]: ../variables#default-values <%= partial '../../code-snippets/example-use-with' %> ## Finding the Module It wouldn't be any fun to write out absolute URLs for every stylesheet you load, so Sass's algorithm for finding a module makes it a little easier. For starters, you don't have to explicitly write out the extension of the file you want to load; `@use "variables"` will automatically load `variables.scss`, `variables.sass`, or `variables.css`. <% heads_up do %> To ensure that stylesheets work on every operating system, Sass loads files by *URL*, not by *file path*. This means you need to use forward slashes, not backslashes, even on Windows. <% end %> ### Load Paths All Sass implementations allow users to provide *load paths*: paths on the filesystem that Sass will look in when locating modules. For example, if you pass `node_modules/susy/sass` as a load path, you can use `@use "susy"` to load `node_modules/susy/sass/susy.scss`. Modules will always be loaded relative to the current file first, though. Load paths will only be used if no relative file exists that matches the module's URL. This ensures that you can't accidentally mess up your relative imports when you add a new library. <% fun_fact do %> Unlike some other languages, Sass doesn't require that you use `./` for relative imports. Relative imports are always available. <% end %> ### Partials As a convention, Sass files that are only meant to be loaded as modules, not compiled on their own, begin with `_` (as in `_code.scss`). These are called *partials*, and they tell Sass tools not to try to compile those files on their own. You can leave off the `_` when importing a partial. ### Index Files If you write an `_index.scss` or `_index.sass` in a folder, the index file will be loaded automatically. when you load the URL for the folder itself. <% example do %> // foundation/_code.scss code { padding: .25em; line-height: 0; } --- // foundation/_lists.scss ul, ol { text-align: left; & & { padding: { bottom: 0; left: 0; } } } --- // foundation/_index.scss @use 'code'; @use 'lists'; --- // style.scss @use 'foundation'; === // foundation/_code.sass code padding: .25em line-height: 0 --- // foundation/_lists.sass ul, ol text-align: left & & padding: bottom: 0 left: 0 --- // foundation/_index.sass @use 'code' @use 'lists' --- // style.sass @use 'foundation' === code { padding: .25em; line-height: 0; } ul, ol { text-align: left; } ul ul, ol ol { padding-bottom: 0; padding-left: 0; } <% end %> ## Loading CSS In addition to loading `.sass` and `.scss` files, Sass can load plain old `.css` files. <% example do %> // code.css code { padding: .25em; line-height: 0; } --- // style.scss @use 'code'; === // code.css code { padding: .25em; line-height: 0; } --- // style.sass @use 'code' === code { padding: .25em; line-height: 0; } <% end %> CSS files loaded as modules don't allow any special Sass features and so can't expose any Sass variables, functions, or mixins. In order to make sure authors don't accidentally write Sass in their CSS, all Sass features that aren't also valid CSS will produce errors. Otherwise, the CSS will be rendered as-is. It can even be [extended][]! [extended]: extend