Icon utilities

Utilities (anchor)

The utilities are designed to work with the default, brand and custom icon variables included by combining the icon's class token with the following utility modifiers:

.ico
.ico-b
.ico-a
.ico-block
.ico-block-center

See the icon examples to view all the icon classes that can be included and custom icons on how to include your own icons to use with the utilities.

Usage (anchor)

The icons are designed as purely decorative CSS so the icons don't interrupt the flow of content, this enables using them in a variety of ways without additional accessibility attributes to describe or hide the icons in the content.

Heading

• Item 1
• Item 2
• Item 3
• Item 4

Download

Options

<h4 class="ico-b info-box">Heading</h4>

<ul class="ul-none tick-box">
<li class="ico-b">Item 1</li>
<li class="ico-b">Item 2</li>
<li class="ico-b close-box">Item 3</li>
<li class="ico-b">Item 4</li>
</ul>

<a href="#" class="ico-a download">Download</a>
<button class="ico-a caret-down">Options</button>

Block

<h4 class="ico-block house">Block</h4>

Block center

<h4 class="ico-block-center house" style="text-align:center;">Block center</h4>

Home

Menu

<span class="ico house" aria-hidden="true"></span>
<a href="#" class="ico house"><span class="vis-hidden">Home</span></a>
<button class="ico bars"><span class="vis-hidden">Menu</span></button>

Customizing (anchor)

CSS variables can be used to customize the icon color, size and vertical alignment, and the margin right and left for icons placed before and after content. View the source code below to see how the CSS variables are applied to the styles.

Heading

• Item 1
• Item 2
• Item 3
• Item 4

Home

Menu

<h3 class="ico-b info-box" style="--ico: Violet; --ico-xy :2.5rem; --ico-va: -.4em">Heading</h3>

<ul class="ul-none tick-box" style="--ico: RoyalBlue; --ico-mr: .75rem;">
<li class="ico-b">Item 1</li>
<li class="ico-b">Item 2</li>
<li class="ico-b close-box" style="--ico: Coral; --ico-mr: 1rem;">Item 3</li>
<li class="ico-b">Item 4</li>
</ul>

<a href="#" class="ico-b house" style="--ico: Brown;">Home</a>
<button class="ico-b bars" style="--ico-op: 0.25;">Menu</button>

Using the module (anchor)

Load StyleMods as demonstrated (change file path as required) then include the Sass mixin anywhere below.

@use "stylemods/scss" as *;
@include icon-utilities-css;
@include icon-links-css;
@include icon-buttons-css;

The icon-links-css and icon-buttons-css provides optional default colors for icons used in both elements.

See the using modules page for more information including how to compile the modules in cascade layers and include and reuse them in multiple source files.

Using the framework (anchor)

Using the recommended custom setup enable the styles in an overrides document:

@use "stylemods/scss/configuration" as *;
$enable-icon-utilities-css:   true;
$enable-icon-links-css:       true;
$enable-icon-buttons-css:     true;

Include the overrides and the framework styles with your custom document for compiling the framework:

@use "overrides";
@use "stylemods/scss/stylemods";

See using the framework for more information including how the styles can also be compiled within cascade layers.

Utility mixin (anchor)

The icon-mask mixin can be used to compile custom icon components using the Sass variables for the icon variables or using any custom icons you've included. Provided in the source code below, it can be used with or without the utilities or the icon variable tokens also being compiled.

@mixin icon-mask {
  display: inline-block;
  content: "";
  block-size: var(--ico-xy, 1em);
  inline-size: var(--ico-xy, 1em);  
  vertical-align: var(--ico-va, -.115em);
  background-color: var(--ico, CanvasText);
  mask-image: var(--svg);
  mask-repeat: no-repeat;
  opacity: var(--ico-op, 1);
}

The Sass variable for each icon (see icon variables source code) can be included with the mixin in your custom style without compiling either the token or utility class:

.home:before {
  --svg: #{$house};
  @include icon-mask;
}

To use the variable values conditionally for styling the variables can be included on the parent instead of including them with a :before or :after pseudo-element:

.home {
  --svg: #{$house};
  --ico: blue;
  --ico-op: 0.5;
}
.home:is(:hover, :focus) {
  --ico: orange;
  --ico-op: 1;
}
.home:before {
  @include icon-mask;
}

If you're compiling the icon variables you can replace the Sass variables with the variable tokens, and any custom icons you've also included can use the mixin and variables the same way.

Source code (anchor)

// ---------------------------------------------------------- 
// Icon utilities
// ----------------------------------------------------------
@mixin icon-mask {
  display: inline-block;
  content: "";
  block-size: var(--ico-xy, 1em);
  inline-size: var(--ico-xy, 1em);  
  vertical-align: var(--ico-va, -.115em);
  background-color: var(--ico, CanvasText);
  mask-image: var(--svg);
  mask-repeat: no-repeat;
  opacity: var(--ico-op, 1);
}

@mixin icon-utilities-css {
  %icon-mask {
    @include icon-mask;
  }
  
  .ico:before {
    @extend %icon-mask;
  }
  
  .ico-b:before { 
    @extend %icon-mask;
    margin-inline-end: var(--ico-mr, calc(1em / 3.75));
  }
  
  .ico-a:after {
    @extend %icon-mask;
    margin-inline-start: var(--ico-ml, calc(1em / 3.75));
  }
  
  .ico-block:before, .ico-block-center:before {
    --ico-va: initial;
    @extend %icon-mask;
    display: block;
    margin-block-end: var(--ico-mb, 0.25rem);
  }
  
  .ico-block-center:before {
    margin-inline: auto;
  }
}

@mixin icon-links-css {
  :where(a) {
    --ico: var(--link, LinkText);
  }
  
  :where(a:is(:hover, :focus)) {
    --ico: var(--hover, color-mix(in srgb, LinkText 75%, white));
  }
}

@mixin icon-buttons-css {    
  :where(button, .btn) {
    --ico: var(--btn-text, buttontext);
  }
}

// Grouped mixins
@mixin all-icon-utilities-css {
  @include icon-utilities-css;
  @include icon-links-css;
  @include icon-buttons-css;
}