Mixins

breakpoint

With the breakpoint mixin, you can create a min-width based (mobile-first) breakpoint on a predefined breakpoint from the $breakpoints map.

The predefined breakpoints are the following:

scss$breakpoints: (
  xs: 32em,
  sm: 48em,
  md: 64em,
  lg: 80em,
  xl: 90em,
  xxl: 110em
);

Argument(s)

Name	Default Value	Description
`$breakpoint`		The name of the key from the `$breakpoints` map.
`$logic`	`false`	Any custom logic next to the `min-width` value connected with the “and” logical operator.

View Source on GitHub

Example(s)

scss.footer {
  display: block;
  align-items: center;

  @include spruce.breakpoint(md) { // @media (min-width: 64em)
    display: flex;
    justify-content: space-between;
  }
}

scss.footer {
  display: block;
  align-items: center;

  @include spruce.breakpoint(md) { // @media screen and (min-width: 64em)
    display: flex;
    justify-content: space-between;
  }
}

Button

btn-variant

Using the btn-variant mixin, you can create a new button variant. First, you must declare the colors of the new button (background, foreground is required) in the $colors map at the very first @use of Spruce.

Argument(s)

Name	Default Value	Description
`$type`	`primary`	The name/prefix of the related colors under the `btn` map.
`$focus`	`true`	Set it `true` if you want to display a focus outline ring.

View Source on GitHub

Example(s)

Declare the colors of the button. The mixin will search for the keys under the btn object.

scss@use '~sprucecss/scss/spruce' with (
  $colors: (
    btn: (
      custom-background: hsl(0, 0%, 95%),
      custom-foreground: hsl(0, 0%, 10%)
    )
  )
);

In many cases, declaring just the background and foreground color is enough. Spruce will generate the rest (hover states). But if you want to control more or use dark mode (where you want to overwrite the color values), you can be more specific.

scss@use '~sprucecss/scss/spruce' with (
  $colors: (
    btn: (
      primary-background: hsl(261 52% 59%),
      primary-background-hover: hsl(261 52% 49%),
      primary-foreground: hsl(0 0% 100%),
      primary-foreground-hover: hsl(0 0% 100%),
      primary-shadow-focus: hsl(261 52% 59% / 0.25),
    )
  )
);

scss.btn--custom {
  @include spruce.btn-variant(custom);
}

html<a href="https://conedevelopment.com" class="btn btn--custom btn--lg">Go to Cone</a>

btn-variant-outline

Using the btn-variant-outline mixin, you can create a new outlined button variant. First, you must declare the colors of the new button (background, foreground is required) in the $colors map at the very first @use of Spruce.

Argument(s)

Name	Default Value	Description
`$type`	`primary`	The name/prefix of the related colors under the `btn` map.
`$focus`	`true`	Set it `true` if you want to display a focus outline ring.

View Source on GitHub

Example(s)

scss.btn--outline-primary { @include btn-variant-outline(primary); }
.btn--outline-secondary { @include btn-variant-outline(secondary); }

font-face

The font-face mixin is a helper to generate a @font-face declaration. This is a minimal and modern font-face declaration, so it only supports the .woff2 format (under the $src argument).

Argument(s)

Name	Default Value	Description
`$font-family`	`null`	The name of the font family.
`$src`	`null`	The URL path to the font file.
`$font-weight`	`400`	The weight of the font.
`$font-style`	`normal`	The style of the font.
`$font-display`	`swap`	The `font-display` property value.

View Source on GitHub

Example(s)

scss@include spruce.font-face(
  'Montserrat',
  '../fonts/montserrat-v25-latin-ext_latin-regular.woff2'
);

@include spruce.font-face(
  'Montserrat',
  '../fonts/montserrat-v25-latin-ext_latin-700.woff2',
  '700'
);

Form

focus-ring

The focus-ring() is a small internal helper mixin to set up the focus state of the form fields, buttons (or anything). We call it on the .form-control, .form-check, .form-switch, .form-range, and button variants. For these calls, it works with global, related variables.

Argument(s)

Name	Default Value	Description
`$type`	`box-shadow`	The type of the focus ring: `outline` or `box-shadow`.
`$border-color`	`null`	The color value of the border. It is needed mostly on inputs.
`$ring-color`		The color of the focus ring.
`$box-shadow-type`		Where should it place the box-shadow: `outside` or `inside`.
`$ring-width`		The width of the focus ring.
`$ring-offset`		The offset of the focus ring if the type is `outline`.

View Source on GitHub

Example(s)

scss.form-control:focus {
  @include spruce.focus-ring(
    $type: $form-control-focus-ring-type,
    $border-color: spruce.color(border-focus, form),
    $ring-color: spruce.color(ring-focus, form),
    $box-shadow-type: $form-control-focus-ring-box-shadow-type,
    $ring-width: $form-control-focus-ring-width,
    $ring-offset: $form-control-focus-ring-offset
  );
}

field-disabled

The field-disabled() is a small internal helper mixin to set up the disabled state on form fields. We call it on the .form-control and .form-check classes.

Argument(s)

Name	Default Value	Description
`$background`		The color value of the background.
`$border`		The color value of the border.

View Source on GitHub

Example(s)

scss.form-control:[disabled],
.form-control:[disabled='true'] {
  @include spruce.field-disabled(
    spruce.color(background-disabled, form),
    spruce.color(border-disabled, form)
  );
}

field-icon

The field-icon() mixin is a getter function for form input backgrounds. Spruce CSS uses custom images (used as inline SVG) for various inputs (checkbox, radio, select, success, error states).

This mixin first replaces the given color value as a fill value on the SVG image then escapes it.

It is helpful for dark mode because we can’t pass a CSS variable to an inline SVG, so we have to overwrite it.

Argument(s)

Name	Default Value	Description
`$icon`		The name of the icon variable.
`$color`		The color value of the fill.

View Source on GitHub

Example(s)

scssselect {
  &:not([multiple]):not([size]) {
    @include spruce.field-icon(
      spruce.$select-image,
      spruce.color(select-foreground, form)
    );
  }
}

form-check

The form-check() mixin is a helper to create custom checkboxes. It accepts three selectors and generates radio and checkbox styles.

There are scenarios (unfortunately) where it is easier to modify the CSS code than the HTML markup. In our case, we usually style the checkboxes and radios in the Custom Form 7 plugin.

Argument(s)

Name	Default Value	Description
`$parent`		The selector of the parent element.
`$input`		The selector of the input element.
`$label`		The selector of the label element.
`$has-sizes`	`false`	Turn on the sizes variants (`--sm`, `--lg`).

View Source on GitHub

Example(s)

scss@include form-check('.form-check', '.form-check__control', '.form-check__label', true);

Layout

layout-center

With the help of the layout-center mixin, you can center any element. It is most useful for the generic container element for the main layouts.

Argument(s)

Name	Default Value	Description
`$gap`	`m`	The padding value on either side of the element. The value comes from the `$spacers` map, use any declared key name for shorthand.
`$max-width`	`spruce.$container-width`	Set the max-width value of the element.

View Source on GitHub

Example(s)

scss.hero {
  &__container {
    @include spruce.layout-center(
      clamp(spruce.spacer(m), 5vw, spruce.spacer(l))
    );
  }
}

layout-stack

Using the help of the layout-stack mixin, you can classical stack layout where the elements are stacked under each other.

Argument(s)

Name	Default Value	Description
`$gap`	`m`	The margin value between the elements. The value comes from the `$spacers` map, use any declared key name for shorthand.
`$width`	`false`	Set `width: 100%;` on the stacked elements.
`$align`	`none`	Set explicit align to the elements(`none`, `left`, `right`).
`$important`	`false`	Add !important on descandent elements to `margin-block-start`.
`$split`	`0`	Split the elements vertically from the nth element.

View Source on GitHub

Example(s)

scssul {
  @include spruce.layout-stack(xs);
}

layout-grid

With the help of the layout-grid mixin you can create auto-fit grid layouts where you can determine the columns' min-width.

Argument(s)

Name	Default Value	Description
`$gap`	`m`	The gutter value between the elements. The value comes from the `$spacers` map, use any declared key name for shorthand.
`$minimum`	`12.5rem`	The minimum value of the child elements where it automatically breaks.

View Source on GitHub

Example(s)

scss.docs-cards {
  &__inner {
    @include spruce.layout-grid(l, 20rem);
  }
}

Using the layout-sidebar mixin, you can create a two-column sidebar layout declaring the sidebar width explicitly.

Argument(s)

Name	Default Value	Description
`$gap`	`m`	The gutter value between the elements. The value comes from the `$spacers` map, use any declared key name for shorthand.
`$sidebar-width`	`18.75rem`	The width of the sidebar element.

View Source on GitHub

Example(s)

scss.docs-template {
  @include spruce.layout-sidebar(l, 22rem);
}

layout-flex

Using the layout-flex mixin, you can create intrinsic flexbox grids with explicit column width.

Argument(s)

Name	Default Value	Description
`$gap`	`m`	The gutter value between the elements. The value comes from the `$spacers` map, use any declared key name for shorthand.
`$width-variable`	`--col-width`	The optimal width of the columns.

View Source on GitHub

Example(s)

scss.form-row--mixed {
  --col-width: 10rem;

  @include spruce.layout-flex;
}

selection

Using the selection mixin, you can simplify the ::selection declarations. Pick a background color value from the base subsection by name and let it calculate the contrast color for the foreground automatically.

Argument(s)

Name	Default Value	Description
`$background`	`primary`	The background color code or the name of the color from the `base` subsection from `$colors` map.
`$foreground`	`null`	The foreground color code. It will get a contrasting pair (black or white) if left empty, based on the background value.

View Source on GitHub

Example(s)

scss.footer {
  // @include spruce.selection(hsl(262 71% 49%));
  @include spruce.selection(secondary);
}

set-css-variable

Declare CSS custom properties through Spruce CSS to add the prefix. To get any CSS variable with prefix use the get-css-variable function.

Argument(s)

Name	Description
`$vars`	A Sass map of key, value pairs.

View Source on GitHub

Example(s)

scss:root {
  @include spruce.set-css-variable((
    --container-gap: spruce.spacer-clamp(m, l)
  ));
}

transition

This mixin aims to query the transition variables easier. Usually, you only need the global values (e.g., for anything with a custom hover animation), but you can also overwrite the three basic arguments.

Argument(s)

Name	Default Value	Description
`$duration`	`duration`	Get the `$transition-duration` value or set a custom one.
`$property`	`all`	Set the `transition-property` to `all`.
`$timing-function`	`timing-function`	Get the `$transition-timing-function` value or set a custom one.

View Source on GitHub

Example(s)

scss.custom-link {
  @include spruce.transition;

  &:hover {
    background-color: pink;
  }
}

Utilities

text-ellipsis

Crop text and display an ellipsis with multiline support where possible.

Argument(s)

Name	Default Value	Description
`$number-of-lines`	`1`	Multiline text cropping where supported.

View Source on GitHub

Example(s)

scss.crop-text {
  @include spruce.text-ellipsis(2);
  width: 20rem;
}

Be careful when using the text-ellipsis mixin with flex displays because it will break.

Hide something from the screen but keep it visible for assistive technology.

View Source on GitHub

Example(s)

scss.sr-only {
  @include spruce.visually-hidden;
}

scrollbar

Create natively styled custom scrollbars.

Argument(s)

Name	Default Value	Description
`$thumb-background-color`	`spruce.color(thumb-background, scrollbar)`	The color of the scrollbar handle.
`$thumb-background-color-hover`	`spruce.color(thumb-background-hover, scrollbar)`	The color of the scrollbar handle on hover state.
`$track-background-color`	`spruce.color(track-background, scrollbar)`	The background color of the scrollbar.
`$size`	`0.5rem`	The width or height of the scrollbar.
`$border-radius`	`spruce.$border-radius-sm`	The border-radius of the scrollbar and handle.

View Source on GitHub

Example(s)

scsscode {
  @include spruce.scrollbar(
    $thumb-background-color: spruce.color(primary)
  );
  background-color: transparent;
  border-radius: 0;
  display: block;
  overflow-x: auto;
  padding: spruce.spacer(xs) 0;
}

clear-btn

Clear the default browser button styles.

View Source on GitHub

Example(s)

scss.remove-button-styles {
  @include clear-btn;
}

clear-list

Remove the list-style, margin, and padding stylings from the element.

View Source on GitHub

Example(s)

scssul {
  @include clear-list;
}

Create better card component linking by only using the title’s link (and not the whole block). Please visit this article about cards by Heydon Pickering for more information about the technique.

Name	Default Value	Description
`$link`		The selector of the link element.
`$at-root`	`false`	Wheater output the link as a child of the parent component or at the root level.

View Source on GitHub

Example(s)

scss.card {
  @include spruce.a11y-card-link('.card__link', true);
  border: 1px solid spruce.color(border);
  border-radius: spruce.$border-radius-lg;
  padding: spruce.spacer(m);

  &__link {
    color: spruce.color(heading);
    font-size: spruce.font-size(h3);
    font-weight: 700;
    text-decoration: none;
  }
}

word-wrap

Break long strings of text.

View Source on GitHub

Example(s)

scss.break-long-url {
  @include spruce.word-wrap;
}

Edit on GitHub

On this page

breakpoint

Argument(s)

Example(s)

Button

btn-variant

Argument(s)

Example(s)

btn-variant-outline

Argument(s)

Example(s)

font-face

Argument(s)

Example(s)

Form

focus-ring

Argument(s)

Example(s)

field-disabled

Argument(s)

Example(s)

field-icon

Argument(s)

Example(s)

form-check

Argument(s)

Example(s)

Layout

layout-center

Argument(s)

Example(s)

layout-stack

Argument(s)

Example(s)

layout-grid

Argument(s)

Example(s)

layout-sidebar

Argument(s)

Example(s)

layout-flex

Argument(s)

Example(s)

selection

Argument(s)

Example(s)

set-css-variable

Argument(s)

Example(s)

transition

Argument(s)

Example(s)

Utilities

text-ellipsis

Argument(s)

Example(s)

visually-hidden

Example(s)

scrollbar

Argument(s)

Example(s)

clear-btn

Example(s)

clear-list

Example(s)

a11y-card-link

Example(s)

word-wrap

Example(s)