Installation

Spruce CSS is built on Sass; to get its full potential, you should use it with Sass. You can load the compiled CSS too, but you will lose the configuration and the helpers.

npm install sprucecss --save

yarn add sprucecss

The package contains two compiled bundles in the css folder, each in a regular and a minified version:

Load them from a CDN:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/sprucecss@3/css/spruce.min.css">
<!-- or, with dark mode and the styles: -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/sprucecss@3/css/spruce.complete.min.css">

Or download the latest release and use the files from the css folder.

The manageability of Spruce CSS comes from its Sass features, variables, mixins, and functions. You should use the preprocessor for the proper workflow (e.g., overwriting the default variables).

With the help of the mixins and functions, you can write code easier.

To import it into your project, use Sass’s @use rule, the module-based successor of @import. Unlike @import, you must @use Spruce in every file where you want to access its variables, functions or mixins.

@use 'sprucecss/scss/spruce' as *;

The @use rule loads the mixins, functions, and variables without a namespace, so you can simply refer to anything by its name:

.section {
  @include layout-stack('m');
}

We include the layout-stack mixin that will make a simple stacked layout.

If you prefer the namespaces, leave the as * part out and use the following:

@use 'sprucecss/scss/spruce';

.section {
  @include spruce.layout-stack('m');
}

Tell Sass where to find the package. The simplest is the load path:

sass --load-path=node_modules src/scss:dist/css

With Sass’s Node package importer (--pkg-importer=node), you can use the pkg: URL, which reads the sass entry point of the package:

@use 'pkg:sprucecss' as *;

Sass lets you configure a module only once, at its first @use. Keep the configuration in one file and load it first:

// config/_config.scss
@use 'sprucecss/scss/spruce' with (
  $settings: (
    'css-custom-properties': true,
  ),
);

// main.scss
@use 'config/config';
@use 'sprucecss/scss/spruce' as *;

@include generate-styles;

Importing Spruce means you load its variables, functions, and mixins. To use its styles, you must include them explicitly with a mixin.

To load the styles, you need to include a generator mixin. A generator (a naming convention in Spruce CSS only) mixin is a wrapper mixin whose goal is to generate a specified style, usually once in your project. These are complete declarations with selectors, so you can’t use them inside code blocks.

You can control the flow of the style generation in a lot of ways (for more information, please visit our Generators page), but there is one main mixin to use:

@use 'sprucecss/scss/spruce' as *;

@include generate-styles;

Depending on your development setup, using Sass could be a burden. We think that Sass is a handy tool and easy to use. Compiling is one of the more significant barriers; for this reason, we wrote a guide about a simple Sass compile setup.