Customizing
Customize default property values with Sass overrides, with CSS variables before and after compiling, or use the Sass maps for expanding, customizing and creating new styles.
Sass variables (anchor)
All the Sass variables with !default values can be customized using overrides as follows:
@use 'stylemods/scss' with (
$h1-font-size: 2.2rem,
$button-radius: 0.25rem,
$blue: royalblue,
);
@use "stylemods/scss" as *;
@include blue-variables-css;
@include typography-css;
@include forms-buttons-css;They can be included with the styles as shown above or in an external document:
@use "overrides";
@use "stylemods/scss" as *;
@include blue-variables-css;
@include typography-css;
@include forms-buttons-css;The Sass variables are all self-contained with the associated style module, the full source code for each is included on the docs pages demonstrating the variables used.
Token styles (anchor)
Where CSS variable tokens mixins are provided by default contained within a :where(html) pseudo-class wrapper style the default value can also be customized to use :root or another selector if preferred or required:
@use 'stylemods/scss' with (
$color-tokens: root,
$theme-tokens: root,
);
@use "stylemods/scss" as *;
@include all-color-variables-css;
@include all-theme-variables-css;Component icons (anchor)
The default SVG icons used with the accordions and alerts components can also be customized with overrides to use icon options provided with each of the modules. The Sass variables from the icons can also be used the same way.
@use 'stylemods/scss' with (
$open-accordion: $accordion-caret-down-icon,
$close-accordion: $accordion-caret-up-icon,
$close-alert: $alert-close-box-icon,
);
@use "stylemods/scss" as *;
@include accordions-css;
@include alerts-css;If included the icons token variables can be used to replace the Sass variables to save replicating the values in two places.
@use 'stylemods/scss' with (
$open-accordion: var(--plus),
$close-accordion: var(--minus),
$close-alert: var(--close),
);
@use "stylemods/scss" as *;
@include accordions-css;
@include alerts-css;There's nothing stopping you from copying and pasting ALL the Sass variables used in StyleMods into a single overrides document to provide your own reusable global file for customizing the default property values.
CSS variables (anchor)
A majority of the styles use property values inherited through fallbacks for empty CSS variables. As fallback values these are also not dependent on global variables unless you choose to include them. If the method doesn't suit, or you want to change the variable names and/or default fallback values, you can use overrides to customize the Sass variables as shown above.
$text-color: var(--text, CanvasText) !default;
$background-color: var(--background, Canvas) !default;
etc.
$h1-font-size: var(--h1-fs, 2.125rem) !default;
$h2-font-size: var(--h2-fs, 1.75rem) !default;
etc.Global variables (anchor)
With no preset values the variables can be used globally for theme design. The optional theme colors leverage the color value variables used in the styles this way to create the tokens to override the default fallback values with (customizable) theme colors.
:where(html) {
--text: light-dark(#444, #eee)
--background: light-dark(PowderBlue, MidnightBlue)
--h1-fs: 2.2rem;
--h2-fs: 1.8rem;
}Component variables (anchor)
You can also use the variables to create custom component styles using semantic elements, classes or ID styles. The color utilities leverage the variables this way to create the optional colored modifier classes for StyleMods components and utilities.
article {
--h1-fs: 3rem;
--h2-fs: 2rem;
--heading-lh: 1.2;
--heading-mb: 1rem;
--para-fs: 1.1rem;
--para-mb: 1.5rem;
--para-tw: balance;
}
section {
--h2-fs: 1.75rem;
--heading-fw: 500;
--heading-mb: 0.25rem;
}
aside {
--h2-fs: 1.3rem;
--list-mb: 0.5rem;
--li-ps: 0.5rem;
--marker: 'square';
}Inline styles (anchor)
You can use the variables with inline HTML styles to customize individual elements on-the-fly:
<h1 style="--h1-fs:4rem;">Hello world!</h1>Like the component variables you can use an inline style on a container to customize child elements:
<section style="--h2-fs:2rem; --para-fs:1.2rem; --marker:'square';">
<h2>More info</h2>
<p>The quick brown fox jumps over the lazy dog.</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
<li>Item 3</li>
</ul>
</section>Sass maps (anchor)
The color, utilities and layout modules all use Sass maps to help generate the individual styles and variables, as does the icons to help generate the SVG icon variable tokens. These are all included as !default value maps so can be used to control and customize what's included as well as expanding existing styles.
You can use any of the default maps to control what's compiled, for example with layout utililities like the grids you can limit the amount of columns included with the utilities when compiled:
@use "sass:map";
@use "stylemods/scss" as *;
$grid-values: (
"g-1": minmax(0, 1fr),
"g-2": repeat(2, minmax(0, 1fr)),
"g-3": repeat(3, minmax(0, 1fr)),
"g-4": repeat(4, minmax(0, 1fr)),
"g-5": repeat(5, minmax(0, 1fr)),
"g-6": repeat(6, minmax(0, 1fr)),
);
@include grid-variables-css;
@include grid-css;You can customize the values directly instead of using overrides for the Sass variables as described above:
@use "sass:map";
@use "stylemods/scss" as *;
$gap-sizes: (
"1": 0.5rem,
"2": 1rem,
"3": 1.5rem,
);
@include gaps-css;To add a single value to a default map you can use map-set values with a variable to include for compiling:
@use "sass:map";
@use "stylemods/scss" as *;
$gap-sizes: map.set($gap-sizes, "6", 3rem);
@include gaps-css;For multiple values you can create a custom map and use map-merge to combine it with the default map to compile both sets of values:
@use "sass:map";
@use "stylemods/scss" as *;
$expanded-sizes: (
"6": 3rem,
"7": 4rem,
);
$gap-sizes: map.merge($gap-sizes, $expanded-sizes);
@include gaps-css;Wherever maps use common values such as the gaps, margins and padding you can merge a custom map with all three to ensure utility modifiers included are consistent:
@use "sass:map";
@use "stylemods/scss" as *;
$expanded-sizes: (
"6": 3rem,
"7": 4rem,
);
$gap-sizes: map.merge($gap-sizes, $expanded-sizes);
$margins-sizes: map.merge($margins-sizes, $expanded-sizes);
$padding-sizes: map.merge($padding-sizes, $expanded-sizes);
@include gaps-css;
@include margins-css;
@include padding-css;Alternatively instead of merging maps you could also just create a custom map to use for common values:
@use "sass:map";
@use "stylemods/scss" as *;
$custom-sizes: (
"1": 0.5rem,
"2": 1rem,
"3": 1.5rem,
);
$gap-sizes: $custom-sizes;
$margins-sizes: $custom-sizes;
$padding-sizes: $custom-sizes;
@include gaps-css;
@include margins-css;
@include padding-css;External maps (anchor)
The custom maps can be included with the styles as shown above or using a different document if preferred:
@use "stylemods/scss" as *;
@use "maps" as *;
<-- mixin modules -->@use "sass:map";
@use "stylemods/scss" as *;
<-- maps -->Like the Sass and CSS variables there's nothing stopping you from creating a reusable global Sass maps document for use with multiple projects. For more information about using Sass maps see the documentation on their website: