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,
• once - only include the file once (this is default behavior),
• multiple - include the file multiple time.

They are explained in following chapters.

Css vs 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.

• If the import statement contains the less option, imported file is treated as less file.
• If the import statement contains the css option, imported file is treated as 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.

Css

Css files import statements are copied into output as they are, without being modified. Compilation process makes only one change: top level css file imports are moved on top of the sheet, right after @charset declarations.

Sample input:

h1 { color: green; }
@import "import/official-branding.css";
@import (css) "import/official-another.css";

Compiles into:

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

Less

Content of imported less file is copied into importing style sheet and compiled together with it. 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.

Imported "library.less":

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

Main file:

@import-multiple "library.less" screen and (max-width: 400px);
@import-multiple "library.less";
.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;
}

Different Import Kinds

There is only one difference between @import, @import-once and @import-multiple statements: how many time can be the same file imported.

The statement @import-once will not import file that was already imported. It does not matter which import statement has been used to import previous file copy nor whether previous import used media queries or not. It ignores also previous import statement location does matter. 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

The statement @import-multiple imports the file whether it was already included or not. 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);

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.