LESS Imports

What Does @import Do in LESS?

@import "filename"; tells the LESS compiler to inline the contents of the referenced file at that exact point, before continuing to process the rest of the current file. The .less extension is optional and assumed by default.

Because imports happen at compile time, variables and mixins defined in an imported file become available in the importing file immediately, there is no runtime cost or extra HTTP request for each imported file.

// variables.less
@primary: #2563eb;

// main.less
@import "variables";

.button {
  background: @primary;
}

The compiler inlines variables.less into main.less before compiling, so @primary is already defined by the time .button uses it.

Import Syntax

@import "filename";
@import (option) "filename";

• The .less extension is optional; @import "buttons"; and @import "buttons.less"; are equivalent.
• Importing a .css file by extension keeps it as a plain, unprocessed @import in the output.
• Import options in parentheses control how a file is imported: reference, inline, css, once, multiple, optional.
• By default, LESS imports each unique file only once (once is the default behavior).

LESS Import Options Cheatsheet

Options you can pass to @import to control its behavior.

Reference Imports

The reference option loads a file so its variables and mixins are available, but suppresses any of its own CSS output unless something is explicitly extended or mixed in from it. This is useful for pulling in a large library of mixins without duplicating unused styles.

@import (reference) "bootstrap-mixins";

.card {
  .make-shadow(); // only this mixin's output is included
}

Organizing Imports in a Main File

A common pattern is a single main.less entry file that imports variables and mixins first, then component files, in an order that respects dependencies.

// main.less
@import "variables";
@import "mixins";
@import "base";
@import "components/buttons";
@import "components/cards";
@import "layout";

Variables and mixins are imported first since later files depend on them.

Importing Plain CSS Files

When you import a file with a .css extension, LESS treats it as a plain CSS @import by default, passing it through untouched rather than processing it as LESS. Use the (less) option to force LESS processing on a .css-named file if needed.

• @import "reset.css"; passes through as a native CSS @import url("reset.css");.
• @import (less) "reset.css"; forces LESS to process the file's contents as LESS syntax.
• Native CSS @import url(...) for external stylesheets is untouched by the LESS compiler either way.

Common Mistakes

• Importing the same large mixin library without the reference option, bloating compiled CSS with unused output.
• Assuming @import behaves like a runtime HTTP request; it's fully resolved at compile time, with zero extra requests.
• Forgetting that .css-extension imports are passed through untouched by default, not processed as LESS.
• Creating circular imports between two files that each depend on variables defined in the other.

Key Takeaways

• @import "file"; inlines another LESS file's contents at compile time.
• The reference option loads variables and mixins without outputting unused CSS.
• .css-extension imports pass through as native CSS imports unless the (less) option is used.
• A single main entry file importing variables, mixins, and components in dependency order keeps large projects organized.