Less Language Import

Less import statements allow style sheets to import both CSS and less style sheets. Only less files import statements are processed, CSS file import statements are kept as they are.

Less supports three import statements:

• @import,
• @import-once,
• @import-multiple - available only since 1.4.0.

Both @import-once and @import-multiple have been deprecated and less.js does not support them. Less4j shows warning if you use them.

Syntax

The import syntax is similar to the one described in css specification. Import statement must be followed by string or url containing location of file to be imported and can have media queries. Additional less import options can be specified in parentheses right after the @import keyword.

@import url("import/blue-theme.css?id=123");
@import (once) url('import/blue-theme.less');
@import (once,less) url('import/blue-theme.less');
@import (multiple) url(import/blue-theme.css) screen and (max-width: 400px);

@import "import/blue-theme.css" screen and (max-width: 400px);
@import 'import/blue-theme.less' handheld;
@import 'import/blue-theme.less';

File location must be written either inside string or url. It supports neither variables, nor functions nor any other expression types. However, it is possible to use variable interpolation inside it.

File names are relative to current file. If the file "/data/main.less" contains @import 'import/lib.less' statement, less will import for "/data/import/lib.less".

Less4j supports "/" as file separator on any platform - use it if you want to compile the same way anywhere. In addition, it supports whatever file separator is standard on platform it runs on. E.g., you have to use "/" on linux and either "/" or "" on windows.

Options

Less supports following options:

• less - treat the file as a Less file, no matter what the file extension,
• css - treat the file as a CSS file, no matter what the file extension,
• reference - use a Less file but do not output it,
• inline - include the source file in the output but do not process it,
• optional - ignore and do not generate error if file does not exist,
• once - only include the file once (this is default behavior),
• multiple - include the file multiple time.

They are explained in following chapters.

Importing Css vs Importing Less

Less treats import of less files differently then import of css files. Less files are copied into importing style sheets and compiled together with them. Importing and imported files share all mixins, namespaces, variables and other structures. In addition, if the import statement had media queries, imported content is enclosed in @Media declaration.

Css files are not copied anywhere, the compiled style sheet contains regular css @import statement.

Which One Is Used

Less uses less and css options to determine whether the file should be treated as less or css file. If neither of these options is specified, less uses file suffix to determine its type.

If the file name ends with suffix ".css" or "/css", then the file is considered to be CSS file. Otherwise it is considered to be less file. Less.js supports also url parameters at the end of the name e.g., file.css?id=123 is considered CSS file. In addition, if the import statement lack any suffix at all, the compiler adds ".less" in the end of the name. Therefore, the attempt to import "my-library" file will include "my-library.less" file.

Example: Css

Sample input:

h1 { color: green; }
@import "import/official-branding.css"; // treated as css because of suffix
@import (css) "import/official-another.less"; // treated as css because of import option - suffix does not matter

Compiles into:

@import "import/official-branding.css";
@import "import/official-anther.less";
h1 { color: green; }

Example Less

Imported "library.less":

@importedColor: red;
h1 {color: green; }

Main file:

@import (multiple) "library.less" screen and (max-width: 400px); // treated as less because of suffix
@import (multiple, less) "library.less"; // treated as less because of option, suffix does not matter
.class {
  color: @importedColor; // use imported variable
}

compiles into:

//corresponds to @import-multiple "library.less" screen and (max-width: 400px);
@media screen and (max-width: 400px) {
  h1 { color: green; }
}
//corresponds to @import-multiple "library.less";
h1 { color: green; }
.class {
  //use imported variable
  color: #ff0000;
}

Inline

If the inline option is used, the content will be copied into output as is. It will not be processed in anyway, so it can be syntactically incorrect.

Example file.css:

.hacked {
  syntactically incorrect content;
}

Following:

@import (inline) "file.css";
* {
  color: red;
}

compiles into:

.hacked {
  syntactically incorrect content;
}
* {
  color: red;
}

Reference

If the reference option is used, the file will be compiled, but its content will NOT be copied into output. However, you can use both variables and mixins defined in it. You can also extend rulesets defined in imported file and extended rulesets will appear in output without original selectors.

Imported file.less:

.imported {
  color: blue;
}
.extend-me {
  color: green;
}

referenced from main file:

@import (reference) "file.less";

.use-mixin {
  .imported();
}
.extending:extend(.extend-me) {}

compiles into:

.extending {
  color: green;
}
.use-mixin {
  color: blue;
}

Optional

The optional option is used if file to be imported may not exist. If that is the case, compilation removes the import statement and does not generate file does not exist error message. The option is ignored if the file to be imported exists.

Main file:

@import (options) "does-not-exist.less";
.grass {
  color: green;
}

compiles into:

.grass {
  color: green;
}

Multiplicity

The once and multiple options specify how many times can be the same file imported.

An import having once option will not import file that was already imported. Second import will be ignored even if the previous one had media queries around it or was located in different scope. The only thing being compared is file name. Example:

// LESS input @import (once) 'lib1.css' handheld; // imported @import (once) 'lib1.css'; // ignored @import (once) "lib2.css"; // imported @import (once) url(lib2.css); // ignored

// CSS output @import-once 'lib1.css' handheld; // statement was ignored @import-once "lib2.css"; // statement was ignored

An import with multiple option imports the file whether it was already included or not. All import once statements inside it will be treated as if they were encountered for the first time. Example:

// LESS input @import (multiple) 'lib1.css' handheld; // imported @import (multiple) 'lib1.css'; // imported @import (multiple) "lib2.css"; // imported @import (multiple) url(lib2.css); // imported

// CSS output @import 'lib1.css' handheld; @import 'lib1.css'; @import "lib2.css"; @import url(lib2.css);

Note 1: The statement @import acts differently before and after 1.4.0. It acts as @import-multiple in all older versions and as @import-once in all less.js versions after 1.4.0. Current version of less4j supports the older pre-1.4.0 behavior, but this WILL change in the future.

Note 2: less4j supports also old @import-once and @import-multiple statements. Those are deprecated and have been already removed from less.js. @import-once behaves the same way as @import (once) and @import-multiple behaves the same way as @import (multiple).