Functions

Functions return values: colors, spacers, sizes and tokens. Use them instead of hardcoded values, and your code follows the configuration, the dark mode and the design styles.

Get color value by key and type name from the $colors map. The $colors map is nested, so you can access the color values by multiple levels, separated into groups.

The function returns a CSS custom property (with a fallback color when the color-fallback setting is on), but you can also get the raw color value by setting $only-color to true.

View Source on GitHub

a {
  color: color('primary');
}

.has-error {
  color: color('danger', 'alert');
}

Get only the color value by key and type name from the $colors map.

View Source on GitHub

a {
  color: color-value('primary');
}

.has-error {
  color: color-value('danger', 'alert');
}

Get a contrast color (black or white) based on the given one. Spruce uses this function internally in the selection mixin.

View Source on GitHub

a {
  color: color-contrast(blue); // returns white (hsl(0 0% 100%))
}

New in v3. Get a transparent version of a color with color-mix(). Unlike Sass color functions, it works at runtime, so the result follows the dark mode and the design styles.

View Source on GitHub

.highlight {
  background-color: color-alpha('primary', 0.1);
  // color-mix(in srgb, var(--spruce-base-color-primary) 10%, transparent)
}

New in v3. Mix a color with white (or any color) with color-mix(), at runtime.

View Source on GitHub

.banner {
  background-color: color-tint('primary', 90%);
  border-color: color-tint('primary', 30%, $with: black);
}

Using the config() function, you can get any key value from any map. It is a wrapper for map.get with a helpful error message.

If you use the CSS custom property mode, always use this function: it returns the proper custom property (like var(--spruce-border-radius-lg)), so your code follows the runtime changes and the styles.

View Source on GitHub

.element {
  border-radius: config('border-radius-lg', $display);
  block-size: 3rem;
  inline-size: 3rem;
}

Get a value from the $font-sizes map by key name. By default, the function gives back a fluid font size using clamp(), which amount you can control using the $scaler value.

View Source on GitHub

.title {
  font-size: font-size('h2');
}

.serial-number {
  color: color('primary');
  font-size: font-size('h3', 30);
}

Add the prefix to a CSS custom property name and return it in a var(). To set a prefixed CSS variable, use the set-css-variable mixin.

View Source on GitHub

.container {
  @include layout-center(
    get-css-variable(--container-gap)
  );
}

New in v3. Get a border radius from the $display map: sm, md, lg or pill. Returns the custom property in custom property mode, so it follows the styles.

View Source on GitHub

.card {
  border-radius: radius('lg');
}

.tag {
  border-radius: radius('pill');
}

It is hard to get generic font sizes that we can use throughout a whole project. Usually, we need unique ones. For this, we can set fluid declaration, similar to the font-size() function.

View Source on GitHub

.testimonial-title {
  font-size: responsive-font-size(4rem, 30);
}

Get a value by key name from the $settings map. Use the $group argument for the nested settings.

View Source on GitHub

@if setting('hyphens') {
  p,
  li,
  h1,
  h2,
  h3,
  h4,
  h5,
  h6 {
    hyphens: auto;
    overflow-wrap: break-word;
  }
}

@if setting('text', 'utilities') {
  // …
}

New in v3. Get a shadow from the $shadows map: xs, sm, md, lg, xl or inner. Returns the custom property in custom property mode, so the design styles can change it (the brutalist style turns them into hard offset shadows).

View Source on GitHub

.card {
  box-shadow: shadow('sm');

  &:hover {
    box-shadow: shadow('lg');
  }
}

Get one or two (separated with a colon) values by key name from the $spacers map.

View Source on GitHub

.prism-code {
  padding: spacer('xs') spacer('m');
}

.prism-code {
  padding: spacer('xs:m');
}

The shorthand syntax is useful when you want separate values for block and inline. It supports two values.

Create a clamp() declaration with values from the $spacers map or from any generic value. The goal of this helper function is to create fluid spacers more easily.

View Source on GitHub

.block {
  padding: spacer-clamp('m', 'l');
}

.block {
  padding: spacer-clamp('xs', 's', '2vw');
}

.block {
  padding: spacer-clamp(2rem, 'l');
}

Replace any specified value in a string.

View Source on GitHub

// Get custom icon background for input and select fields
@mixin field-icon(
  $icon,
  $color
) {
  background-image: url('#{svg-escape(str-replace($icon, "#COLOR#", $color))}');
}

Escape the special characters in SVG when used as a data:image. The characters are declared under the $escaping-characters map.

View Source on GitHub

// Get custom icon background for input and select fields
@mixin field-icon(
  $icon,
  $color
) {
  background-image: url('#{svg-escape(str-replace($icon, "#COLOR#", $color))}');
}

New in v3. Get a layer value from the $z-indexes map, so overlapping components stack in a predictable order: dropdown, sticky, fixed, overlay, modal, popover, toast, tooltip.

View Source on GitHub

.site-header {
  position: sticky;
  z-index: z-index('sticky');
}