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, see the source code below to view how the CSS variables are applied.

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.

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.

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: var(--svg) 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)

The Icon utilities source file is included with the icons module files, you can view the source code from the latest release (v1.5.0) via the Github link below.

Source document

stylemods/scss/icons/icon-utilities.scss

View on Github

https://github.com/pmbrown/StyleMods/blob/main/scss/icons/icon-utilities.scss

Shared documentation about how to customize the default property values for the styles using the Sass and CSS variables is provided on the customizing page.