Mixins output reusable declarations: layouts, breakpoints, button variants, focus rings and accessibility helpers. They help you write less, more consistent code.
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 | Whether output the link as a child of the parent component or at the root level. |
.card {
@include a11y-card-link('.card__link', true);
border: 1px solid color('border');
border-radius: config('border-radius-lg', $display);
padding: spacer('m');
&__link {
color: color('heading');
font-size: font-size('h3');
font-weight: 700;
text-decoration: none;
}
}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:
$breakpoints: (
'xs': 32em,
'sm': 48em,
'md': 64em,
'lg': 80em,
'xl': 90em,
'xxl': 110em,
);| 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. |
.footer {
display: block;
align-items: center;
@include breakpoint('md') { // @media (min-width: 64em)
display: flex;
justify-content: space-between;
}
}New in v3. A media query between two breakpoints (the lower one inclusive, the upper one exclusive), with the range syntax.
| Name | Description |
|---|---|
$min | The name of the lower breakpoint. |
$max | The name of the upper breakpoint. |
.sidebar {
@include breakpoint-between('md', 'xl') { // @media (64em <= width < 90em)
inline-size: 14rem;
}
}New in v3. A max-width based (desktop-first) media query: the content applies below the breakpoint.
| Name | Description |
|---|---|
$breakpoint | The name of the key from the $breakpoints map. |
.navigation {
@include breakpoint-down('md') { // @media (width < 64em)
display: none;
}
}Using the btn-variant mixin, you can create a new button variant. First, you must declare the colors of the new button (the background and the foreground are required) under btn in the $colors map, at the first @use of Spruce.
| 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. |
Declare the colors of the button. The mixin will search for the keys under the btn object.
@use 'sprucecss/scss/spruce' with (
$colors: (
'btn': (
'custom-background': hsl(0deg 0% 95%),
'custom-foreground': hsl(0deg 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.
@use 'sprucecss/scss/spruce' with (
$colors: (
'btn': (
'primary-background': hsl(261deg 52% 59%),
'primary-background-hover': hsl(261deg 52% 49%),
'primary-foreground': hsl(0deg 0% 100%),
'primary-foreground-hover': hsl(0deg 0% 100%),
'primary-focus-ring': hsl(261deg 52% 59% / 0.25),
),
),
);.btn--custom {
@include btn-variant('custom');
}<a href="https://conedevelopment.com" class="btn btn--custom btn--lg">Go to Cone</a>Using the btn-variant-outline mixin, you can create a new outlined button variant. First, you must declare the colors of the new button (the background and the foreground are required) under btn in the $colors map, at the first @use of Spruce.
| 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. |
.btn--outline-primary { @include btn-variant-outline('primary'); }
.btn--outline-secondary { @include btn-variant-outline('secondary'); }New in v3. A transparent button that gets a translucent background (a color-mix() of the variant color) on hover. Set the *-ghost-foreground and *-ghost-background-hover colors for full control.
| Name | Default Value | Description |
|---|---|---|
$type | 'primary' | The name/prefix of the related colors under the btn map. |
$focus | true | Whether to output the focus ring. |
.btn--ghost-brand { @include btn-variant-ghost('brand'); }New in v3. A button that looks like a link but keeps the button sizing. It uses the link and link-hover colors.
.btn--link { @include btn-variant-link; }New in v3. A tinted button: a light mix of the variant color as the background and the variant color as the text. Set the *-soft-background, *-soft-background-hover and *-soft-foreground colors for full control.
| Name | Default Value | Description |
|---|---|---|
$type | 'primary' | The name/prefix of the related colors under the btn map. |
$focus | true | Whether to output the focus ring. |
.btn--soft-brand { @include btn-variant-soft('brand'); }Clear the default browser button styles.
.remove-button-styles {
@include clear-btn;
}Remove the list-style, margin, and padding stylings from the element.
ul {
@include clear-list;
}New in v3. A container query (inline-size >) with a breakpoint name or any size. The parent needs container-type: inline-size.
| Name | Default Value | Description |
|---|---|---|
$size | A breakpoint name or a size value. | |
$name | null | The name of the container (optional). |
.card-wrapper {
container-type: inline-size;
}
.card {
display: grid;
@include container-query(30rem) {
grid-template-columns: 10rem 1fr;
}
}New in v3. Make an element fill its positioned parent (inset: 0).
| Name | Default Value | Description |
|---|---|---|
$position | absolute | The position value. |
.hero__overlay {
@include cover;
background-color: color-alpha('heading', 0.5);
}New in v3. Output styles for the dark mode, based on the dark-mode settings (the selector and the optional prefers-color-scheme media query). Use it at the root level with rules, or inside a rule with declarations.
| Name | Default Value | Description |
|---|---|---|
$scope | null | An optional scope selector inside the dark mode (used by styles). |
.logo {
filter: none;
@include dark-mode {
filter: invert(1);
}
}
@include dark-mode {
.illustration { opacity: 0.85; }
}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.
| Name | Description |
|---|---|
$background | The color value of the background. |
$border | The color value of the border. |
.form-control:[disabled],
.form-control:[disabled='true'] {
@include field-disabled(
color('background-disabled', 'form'),
color('border-disabled', 'form')
);
}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.
| Name | Description |
|---|---|
$icon | The name of the icon variable. |
$color | The color value of the fill. |
select {
select.form-control:not([multiple]):not([size]) {
@include field-icon(
config('select', $form-icon, false),
color('select-foreground', 'form')
);
}
}
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.
| 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-size | The width of the focus ring. | |
$ring-offset | The offset of the focus ring if the type is outline. |
.form-control:focus {
@include focus-ring(
$type: config('focus-ring-type', $form-control, false),
$border-color: color('border-focus', 'form'),
$ring-color: color('ring-focus', 'form'),
$box-shadow-type: config('focus-ring-box-shadow-type', $form-control, false),
$ring-size: config('focus-ring-size', $form-control, false),
$ring-offset: config('focus-ring-offset', $form-control, false)
);
}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).
| 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. |
@include font-face(
'Montserrat',
'../fonts/montserrat-v25-latin-ext_latin-regular.woff2'
);
@include font-face(
'Montserrat',
'../fonts/montserrat-v25-latin-ext_latin-700.woff2',
'700'
);The checkbox and radio styles come from the generate-form-check() generator mixin. It accepts three selectors, so you can apply the Spruce look to markup you can’t change.
There are scenarios (unfortunately) where it is easier to modify the CSS code than the HTML markup. For example, we usually style the checkboxes and radios of the Contact Form 7 plugin this way.
| 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). |
@include generate-form-check(
'.wpcf7-list-item label',
'.wpcf7-list-item input',
'.wpcf7-list-item .wpcf7-list-item-label'
);Using the form-group-stacked mixin, you can create a stacked form group with a breakpoint. Under the breakpoint, the items stack vertically.
| Name | Default Value | Description |
|---|---|---|
$breakpoint | 'sm' | The breakpoint. |
.form-group--stacked\:md {
@include form-group-stacked('md');
}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.
| 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-inline-size | config('container-inline-size', $layout) | Set the max-inline-size (max-width) value of the element. |
.hero {
&__container {
@include layout-center(
spacer-clamp('m', 'l')
);
}
}New in v3. Inline items that wrap, with a gap: tags, buttons, navigation links.
| Name | Default Value | Description |
|---|---|---|
$gap | 's' | The gap (a spacer key, a 'm:l' shorthand or any value). |
$justify | flex-start | The justify-content value. |
$align | center | The align-items value. |
.tag-list {
@include layout-cluster('xs');
}Using the layout-flex mixin, you can create intrinsic flexbox grids with explicit column width.
| 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. |
$inline-size | --inline-size | The optimal width of the columns. |
.form-row--mixed {
--inline-size: 10rem;
@include layout-flex;
}For the $gap you can also use a shorthand like in the spacer() function for setting separate value for the block and inline gap.
.form-row--mixed {
--inline-size: 10rem;
@include layout-flex('m:l');
}With the help of the layout-grid mixin you can create auto-fit grid layouts where you can determine the columns' min-width.
| 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. |
.docs-cards {
&__inner {
@include layout-grid('l', 20rem);
}
}For the $gap you can also use a shorthand like in the spacer() function for setting separate value for the block and inline gap.
.docs-cards {
&__inner {
@include layout-grid('m:l', 20rem);
}
}New in v3. A horizontally scrollable row with scroll snapping.
| Name | Default Value | Description |
|---|---|---|
$item-inline-size | 18rem | The width of the items. |
$gap | 'm' | The gap between the items. |
.product-row {
@include layout-reel(16rem, 's');
}Using the layout-sidebar mixin, you can create a two-column sidebar layout declaring the sidebar width explicitly.
| 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. |
$inline-size | 18.75rem | The width of the sidebar element. |
.docs-template {
@include layout-sidebar('l', 22rem);
}For the $gap you can also use a shorthand like in the spacer() function for setting separate value for the block and inline gap.
.docs-template {
@include layout-sidebar('m:l', 22rem);
}Using the help of the layout-stack mixin, you can classical stack layout where the elements are stacked under each other.
| 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. |
$inline-size | false | Whether it has explicit width (inline-size). |
$align | none | Set explicit align to the elements(none, left, right). |
$important | false | Add !important on descendant elements to margin-block-start. |
$split | 0 | Split the elements vertically from the nth element. |
ul {
@include layout-stack('xs');
}New in v3. A row of equal columns that switches to a column under a container width, without media queries. Over the $limit number of items, it is always stacked.
| Name | Default Value | Description |
|---|---|---|
$threshold | 30rem | The container width where the layout switches. |
$gap | 'm' | The gap between the items. |
$limit | 4 | The maximum number of items in a row. |
.features {
@include layout-switcher(40rem, 'l');
}New in v3. Output the content only when the user prefers reduced motion.
.spinner {
@include motion-reduce {
animation-duration: 3s;
}
}New in v3. Output the content only when the user doesn't prefer reduced motion. Wrap every non-essential animation in it.
.card {
@include motion-safe {
transition: translate 0.2s ease;
&:hover {
translate: 0 -2px;
}
}
}Create natively styled custom scrollbars.
| Name | Default Value | Description |
|---|---|---|
$thumb-background-color | color(thumb-background, scrollbar) | The color of the scrollbar handle. |
$thumb-background-color-hover | color(thumb-background-hover, scrollbar) | The color of the scrollbar handle on hover state. |
$track-background-color | color(track-background, scrollbar) | The background color of the scrollbar. |
$size | 0.5rem | The width or height of the scrollbar. |
$border-radius | config('border-radius-sm', $display) | The border-radius of the scrollbar and handle. |
code {
@include scrollbar(
$thumb-background-color: color('primary')
);
background-color: transparent;
border-radius: 0;
display: block;
overflow-x: auto;
padding: spacer('xs') 0;
}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.
| 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. |
.footer {
// @include selection(hsl(262deg 71% 49%));
@include selection('secondary');
}Declare CSS custom properties through Spruce CSS to add the prefix. To get any CSS variable with prefix use the get-css-variable function.
| Name | Description |
|---|---|
$vars | A Sass map of key, value pairs. |
:root {
@include set-css-variable((
--container-gap: spacer-clamp('m', 'l')
));
}A shorthand function to get the default focus ring styles for input and button elements.
| Name | Default Value | Description |
|---|---|---|
$type | 'input' | The type of the focus ring. It can be input or button. |
$btn-type | 'primary' | The color - or button type - of the button (if the $type is button) to match the ring color. |
.search-form {
&:focus-visible input[type='search'] {
@include short-ring('input');
}
}
.accordion-card {
&:focus-visible svg {
@include short-ring('button', 'secondary');
}
}Crop text and display an ellipsis with multiline support where possible.
| Name | Default Value | Description |
|---|---|---|
$number-of-lines | 1 | Multiline text cropping where supported. |
.crop-text {
@include text-ellipsis(2);
inline-size: 20rem;
}Be careful when using the text-ellipsis mixin with flex displays because it will break.
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.
| Name | Default Value | Description |
|---|---|---|
$duration | config('duration', $transition) | The default duration value is 0.15s. |
$property | all | Set the transition-property to all. For multiple value use quotes like 'transition, color'. |
$timing-function | config('timing-function', $transition) | The default timing-function value is ease-in-out. |
.custom-link {
@include transition;
&:hover {
background-color: pink;
}
}Hide something from the screen but keep it visible for assistive technology.
.sr-only {
@include visually-hidden;
}New in v3. Visually hide an element until it, or an element inside it, gets the focus. Use it for skip links.
.skip-link {
@include visually-hidden-focusable;
}Break long strings of text.
.break-long-url {
@include word-wrap;
}
