Sass Partials and Import — Complete Guide

In this tutorial, you will learn about Sass Partials and Import. We cover key concepts, practical examples, and best practices to help you master this topic.

Sass partials organize stylesheets into modular files using @use and @forward, controlling variable scope, namespacing, and avoiding duplicate compilation.

What You'll Learn

• Partial files with underscore prefix
• The @use rule for loading modules
• Namespace control with @use
• The @forward rule for re-exporting
• The deprecated @import vs modern @use
• Built-in Sass modules (sass:color, sass:math)
• File organization patterns

Why It Matters

• Large stylesheets must be split into manageable files
• @use prevents variable conflicts with namespacing
• Only loaded once, avoiding duplicate output
• Clear dependencies improve maintainability

Real-World Use

• A design system splits variables, mixins, and components into partials
• A theme system uses @forward to combine dark and light themes
• A utility library uses @use to load only needed modules
• A build pipeline compiles from a single entry point

flowchart LR
  A[main.scss] --> B[@use variables]
  A --> C[@use mixins]
  A --> D[@use components]
  B --> E[_variables.scss]
  C --> F[_mixins.scss]
  D --> G[_components.scss]
  D --> H[_card.scss]
  D --> I[_button.scss]

Modern Module System

Code Example: vs @import

// DEPRECATED: @import (will be removed in future versions)
// @import 'variables';
// @import 'mixins';
// @import 'card';

// MODERN: @use (recommended)
@use 'variables';
@use 'mixins';
@use 'card';

// @use with namespace
@use 'variables' as v;
@use 'mixins' as m;
@use 'card' as c;

body {
    color: v.$primary;
    font-family: v.$font-stack;
}

.button {
    @include m.button-variant(v.$primary);
}

// Namespace is derived from filename by default
// @use 'variables' -> variables.$primary
// @use 'mixins' -> mixins.button-variant()
// @use 'card' -> card.$padding, card.card()

// No namespace with as *
@use 'variables' as *;

body {
    color: $primary;  // Now accessible without namespace
}

Expected output: @use loads each module only once (no matter how many times it is imported) and scopes variables/mixins/functions to a namespace by default.

Code Example: Partial File Structure

// _variables.scss - Core design tokens
$primary: #0066CC;
$secondary: #6c757d;
$font-family: 'Inter', system-ui, sans-serif;
$spacing-unit: 8px;

// _mixins.scss - Reusable mixins
@use 'variables' as *;

@mixin respond-to($breakpoint) {
    @if $breakpoint == 'md' {
        @media (min-width: 768px) { @content; }
    } @else if $breakpoint == 'lg' {
        @media (min-width: 1024px) { @content; }
    }
}

// _card.scss - Card component
@use 'variables' as v;
@use 'mixins' as m;

.card {
    padding: v.$spacing-unit * 2;
    background: #fff;
    border: 1px solid #eee;

    &__title {
        font-size: 1.25rem;
    }

    @include m.respond-to('md') {
        display: flex;
    }
}

// main.scss - Entry point
@use 'variables';
@use 'mixins';
@use 'card';
@use 'button';
@use 'layout';

Expected output: Each partial is a module with its own namespace. The entry point (main.scss) loads all partials. Variables from _variables.scss are accessible in other files with the variables.$primary namespace.

Code Example: @forward for Re-exporting

// _colors.scss
$primary: #0066CC;
$secondary: #6c757d;
$success: #28a745;

// _typography.scss
$font-family: 'Inter', sans-serif;
$font-size-base: 16px;

// _index.scss - Barrel file that re-exports
@forward 'colors';
@forward 'typography';

// Use the barrel file
// main.scss
@use 'index' as *;

body {
    color: $primary;        // From colors
    font-family: $font-family;  // From typography
}

// @forward with prefix
@forward 'colors' as color-*;

// Now used as:
// @use 'index' as *;
// body { color: $color-primary; }

// @forward with hide/show
@forward 'colors' hide $secondary;
// $secondary is NOT available to consumers

Expected output: @forward passes through variables, mixins, and functions from one module to another. Barrel files (_index.scss or _index.scss) re-export multiple partials as a single public API.

Code Example: Built-in Sass Modules

// Built-in Sass modules (sass: prefix)
@use 'sass:color';
@use 'sass:math';
@use 'sass:map';
@use 'sass:list';
@use 'sass:meta';
@use 'sass:string';
@use 'sass:selector';

// sass:color
$primary: #0066CC;
.element {
    background: color.adjust($primary, $lightness: 10%);
    border-color: color.mix($primary, #fff, 80%);
}

// sass:math
.element {
    width: math.div(100%, 3);          // 33.33333%
    padding: math.clamp(16px, 2vw, 32px); // Clamp function
}

// sass:map
$breakpoints: (
    'sm': 480px,
    'md': 768px,
    'lg': 1024px
);

$has-key: map.has-key($breakpoints, 'md');     // true
$keys: map.keys($breakpoints);                 // 'sm', 'md', 'lg'

// sass:list
$fonts: 'Inter', 'Helvetica', Arial;
$first: list.nth($fonts, 1);                   // 'Inter'
$length: list.length($fonts);                  // 3

// sass:meta
@mixin add-global-styles {
    @if meta.global-variable-exists('primary') {
        color: $primary;
    }
}

// sass:string
.element {
    content: string.quote(unquote("Hello"));   // "Hello"
}

// sass:selector
// Useful for advanced selector manipulation

Expected output: Built-in modules provide comprehensive utility functions without external dependencies. They replace older global functions (darken, lighten, etc.) with namespaced module functions.

Common Mistakes

1. Using deprecated @import — @import is deprecated in Dart Sass and will be removed. Use @use and @forward.
2. Not using namespaces — @use 'variables' as * pollutes the global scope. Prefer named namespaces for clarity.
3. Circular dependencies — File A @use File B and File B @use File A creates a circular dependency error.
4. Forgetting the file extension — @use 'variables' loads _variables.scss. No need for the extension, but the path must be correct.
5. Not using a barrel file for component libraries — @forward from an _index.scss simplifies imports for consumers.
6. Loading third-party libraries without @use — Many npm packages provide Sass files that should be loaded with @use.
7. Duplicate loading — @use loads each module once. If two files @use the same partial, the partial runs only once, which is efficient but can be surprising if you expected it to run multiple times.

Practice Questions

1. What is the naming convention for Sass partials? Files starting with underscore (e.g., _variables.scss). The underscore tells Sass not to compile the file independently.
2. How do you load a module with a custom namespace? @use 'filename' as custom-name. Without as, the namespace is the filename.
3. What is the difference between @use and @forward? @use loads a module and makes its members available in the current file. @forward re-exports members so other files can use them.
4. How do you access built-in Sass math functions? @use 'sass:math' and then call math.div(), math.clamp(), etc.

FAQ

Mini Project

Create a complete Sass project structure using the modern module system. Create these partials: _variables.scss (design tokens), _reset.scss (CSS reset), _typography.scss (type scale), _mixins.scss (responsive, button-variant), _components-index.scss (@forward for all components), _button.scss (button system), _card.scss (card component), _grid.scss (responsive grid), _utilities.scss (utility classes). The main.scss entry point uses only @use with namespaces. Demonstrate that variables are scoped (not available without namespace). Show @forward in the barrel file. Verify no deprecation warnings appear during compilation.

What's Next

Continue with Lesson 9: Sass Control Directives to learn conditionals and loops in Sass.