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. |
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. |
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. |
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. |
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 . |
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. |
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. |
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 ). |
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. |
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. |
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. |
Example(s)
scss.docs-cards { &__inner { @include spruce.layout-grid(l, 20rem); }}
layout-sidebar
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. |
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. |
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. |
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. |
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. |
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. |
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.
visually-hidden
Hide something from the screen but keep it visible for assistive technology.
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. |
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.
Example(s)
scss.remove-button-styles { @include clear-btn;}
clear-list
Remove the list-style
, margin
, and padding
stylings from the element.
Example(s)
scssul { @include clear-list;}
a11y-card-link
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. |
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.
Example(s)
scss.break-long-url { @include spruce.word-wrap;}