Settings

In Spruce CSS, the settings are global options controlled through a Sass map.

You can access any setting with the setting() helper function. Below, you can see the $settings map with its default values. The map is deep-merged, so you only need to set the keys you change.

View Source on GitHub

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'accent-color': true,
    'color-fallback': false,
    'css-custom-properties': false,
    'dark-mode': (
      'light-selector': '[data-theme-mode="light"]',
      'prefers-color-scheme': false,
      'selector': ':root[data-theme-mode="dark"]',
    ),
    'html-smooth-scrolling': true,
    'hyphens': true,
    'optimal-font-size': '2vw + 1rem',
    'optimal-spacer-size': '5vw',
    'prefix': 'spruce',
    'print': false,
    'reduced-motion': false,
    'scaler': 15,
    'scroll-margin': null,
    'style-hooks': true,
    'styles': (
      'attribute': 'data-spruce-style',
      'default': null,
      'include': null,
    ),
    'utilities': (
      'display': true,
      'layout': false,
      'text': false,
      'typography': true,
    ),
  ),
);

New in v3. Sets accent-color on the html element to the primary color, so the native controls that Spruce doesn’t style (like a bare checkbox) match your brand. Set it to false to turn it off.

Setting the color-fallback key to true turns on the color fallback of the color() function.

// Without fallback
body {
  // color: color('text');
  color: var(--spruce-base-color-text);
}

// With fallback
body {
  // color: color('text');
  color: var(--spruce-base-color-text, #616c75);
}

By default, Spruce generates CSS custom properties only for the colors and the transition settings. Set this option to true to get custom properties for the typography, display, buttons, form elements, tables and more, which you can change without compiling.

The custom property mode is required by the style presets and the style hooks.

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

New in v3. The options of the dark mode generator and the dark-mode mixin.

Turn off the smooth scrolling (scroll-behavior: smooth;) on the html element. You may need this when you work with a SPA, where it interferes with the route transitions. The smooth scrolling is applied only when the user doesn't prefer reduced motion.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'html-smooth-scrolling': false,
  ),
);

By default, Spruce uses a simple hyphenation setup on paragraphs, list items and headings (see the source).

Turn off the hyphenation:

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'hyphens': false,
  ),
);

The optimal font size used by the font-size() and responsive-font-size() functions as the middle value of clamp().

You can modify this value per function call too. A global default is a must, but bigger sizes usually need fine-tuning.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'optimal-font-size': '5vw + 1rem',
  ),
);

• font-size()
• responsive-font-size()
• clamp()

The optimal spacer size used by the spacer-clamp() function as the middle value of clamp(). You can modify it per function call too.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'optimal-spacer-size': '4vw',
  ),
);

• spacer-clamp()

The prefix of the generated CSS custom properties.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'prefix': 'my-prefix',
  ),
);

Generated CSS custom properties:

:root {
  --my-prefix-alert-color-danger: #db2929;
  --my-prefix-alert-color-info: #00a1d6;
  --my-prefix-alert-color-success: #00a854;
  --my-prefix-alert-color-warning: #f2ca26;
}

Set it to null to remove the prefix.

View Source on GitHub

Spruce comes with a small set of print styles. To turn them on, set the print value to true.

New in v3. When true, Spruce turns off (nearly) all animations and transitions for users who prefer reduced motion, with a global @media (prefers-reduced-motion: reduce) rule. Spruce’s own animations already respect the preference; this option is a safety net for the rest of your project.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'reduced-motion': true,
  ),
);

The global scaler value of the font size functions: how much smaller (in percentage) the fluid sizes get on small screens.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'scaler': 20,
  ),
);

New in v3. Set a length (like 2rem, or the height of your sticky header) to add a scroll-margin-block-start to the :target element, so in-page anchors don’t end up under a sticky header.

New in v3. In custom property mode, every component custom property reads a namespaced hook first (like --spruce-btn-padding), so you can change a component from any ancestor. Set it to false to get the plain v2 output. Learn more about the hooks.

New in v3. The options of the style presets.

Spruce uses only a few classic utility classes. The new groups are opt-in.

@use 'sprucecss/scss/spruce' with (
  $settings: (
    'utilities': (
      'display': true,
      'layout': true,
      'text': true,
      'typography': true,
    ),
  ),
);

See the Utilities and Layout pages for the complete list.