← Building Custom Sites Processes

How to Use Bootstrap's Icons

Recently, we made the change to use Bootstrap’s built-in icon library, and creating custom SVG icons where those fail. The setup of files and installation is also different as a result of this change.

The simplest reason for the change is that with the old iconfont method, if a page took to long to load or the internet connection was too slow, some mobile devices would automatically fill in the iconfonts with emojis instead. This could cause confusion at best, since the emoji is most likely not similar to the icon it’s replacing, and offense at worst, due to the variety of emojis that exist. This new solution loads the iconfonts much more quickly to avoid this issue.

This doc will go over how to use iconfonts in various scenarios, and how to create a custom icon if the default Bootstrap icons aren’t what you need.

Resources

Here is a link to the complete list of Bootstrap icons. This list is updated quite often, so if they don’t have something that you need one day, check back later and they may have added it in. You can use the search function to narrow down the list as well.

How to Create an Icon

Bootstrap’s library of icons is large and expanding daily, but it may not meet your needs fully–or an icon they have may be close to what is in your design, but not perfect. Here is how to make a custom icon that you can use in your build.

For Sketch / Abstract

First, if you are in Abstract, open the file in Sketch by clicking the button with the yellow diamond in the upper right that says “open untracked”. This will open the file in Sketch.

Find the icon in sketch and select it. Make sure that it is the only thing you have selected.

In the right-side pane, there is a panel titled “Make Exportable” that will appear when you have your icon selected. Click that panel and it will open up into a panel that says simply “Export” at the top. Within that panel, there is a set of 3 dropdowns–one for size, one for prefix/suffix, and one for format. You can ignore the first two, and select “SVG” in the third dropdown. You will usually see the icon become visibly clearer and less pixelated when you do this.

Click the “Export Selected…” button at the bottom of the pane. It will bring up the file save window. Navigate to your site’s repo, then go into src > images > svgs > custom. Save your icon with a name that is short, yet descriptive, so you can find and remember it easily.

Lastly, you’ll need to open your new SVG file in your text editor of choice. For simple icons, you will notice that there is a fill property with a hex color value in it–for more complex icons, there may be several instances of a fill property with the same color in it throughout the SVG. Select that and change it instead to be fill="currentColor". If you see anything like fill="none" or fill-rule="evenOdd", you don’t need to worry about those.

How to Place an Icon

In HTML (with styling)

This is the preferred way to place an icon, since it doesn’t rely on before/after pseudo-classes that can get flagged by ADA (though if they do get flagged, you can usually dismiss this as a false-positive because most icons are solely decorative).

Find the icon you want to use.

See above for creation instructions if you need your own icon, or figure out which one of Bootstrap’s icons you want to use.

Installing icons

If you’re using an icon provided by Bootstrap… 1. Go into your gulpfile.json and find the bs-icons gulp task. You will see a list of the existing icons for the site, usually starting with social media icons like Facebook and Twitter. 2. Add the Bootstrap icon you want to include to that list, in the same format. 3. Once you’ve done that, make sure to run npm install in iTerm.

If you are using a custom icon, you do not need to list it in the gulpfile.

Set up icon in the HTML.

This is the HTML setup for an icon provided by bootstrap:

<svg class="bs-icon">
	<use href="#list"/>
</svg>

The #list in the second line refers to the name of the icon that should show.

For custom icons, you will call the icon as #custom--icon. Note the two dashes before the name of the icon.

Style the icon with SCSS.

The one thing that all icons need with this new setup is for their size to be defined. You can do that with this mixin:

@include iconSize(15px);

The px value that you put into the mixin reflects the height that you want the icon to be.

Other optional styles include, but are not limited to:

  • color: The color that you want the icon to be. You can also change this on hover.
  • @include zoomHover();: The zoomHover mixin, helpful for things like close buttons.
  • display: To define whether the icon shows on a new line (block) or is on the same line as other things in its area inline-block. If you are using the @include zoomHover(); mixin, your icon must have one of these two things.
  • ‘vertical-align: middle;’: To make your inline-block icon be vertically center-aligned with other inline-block sibling items.

Via CSS only

This method is different from the above in that you’re not actually placing the icon in the HTML, and instead setting it purely via CSS. This is helpful for things like arrows within menu items, where you can’t edit the HTML, but have full control over the CSS.

Installing icons

If you’re using an icon provided by Bootstrap… 1. Go into your gulpfile.json and find the bs-icons gulp task. You will see a list of the existing icons for the site, usually starting with social media icons like Facebook and Twitter. 2. Add the Bootstrap icon you want to include to that list, in the same format. 3. Once you’ve done that, make sure to run npm install in iTerm.

If you are using a custom icon, you do not need to list it in the gulpfile.

Setting Up the CSS

You can set up your icon to display as a pseudo-before/after class with this CSS, all of which is necessary.

Make sure to substitute in your own values for mask, width, height, mask-size, and background-color.

&:after {
	content: '';
	mask-position: center;
	mask: url(/assets/img/svgs/dash.svg);
	width: 00px;
	height: 99px;
	mask-size: 00px 99px;
	background-color: $yourColor;
}

Here is an explanation of why each of the above properties is necessary:

  • content: '';: Must be defined, and must be empty. You are going to be adding the icon and styling it within this space you create.
  • mask-position: center;: Defines that the icon will display in the center of the space you create.
  • mask: url(/assets/img/svgs/youricon.svg); OR mask: url(/assets/img/svgs/custom/yourcustomicon.svg);: Includes the icon that you want to use. Note that if you are using a custom icon, you must also go into the /custom/ folder within assets/img/svgs.
  • width: 00px;: 00px is an example value. This is the width that you want the icon to be. This value should also be matched as the first part of the mask-size property.
  • height: 99px;: 99px is an example value. This is the height that you want the icon to be. This value should also be matched as the second part of the mask-size property.
  • mask-size: 00px 99px;: 00px 99px is an example value. This is the width and height that you want the icon to be. These values should be matched to the width and height values above.
  • background-color: $yourColor;: $yourColor is an example value. This is the color that you want your icon to be. It is equivalent to the color property that you would set on an icon placed via HTML.

Troubleshooting

Icon is not displaying properly on the published page

Sometimes, if an icon is created using line elements, the iconfont compiler has trouble reading those line elements, so you need to convert them into “outlines”, or a solid object rather than a line. You may need to re-save the icon from Sketch, but before you save it out, go to the Layer menu and select “Convert to Outlines”. You can also do this in Illustrator if you’re more comfortable editing the existing icon there rather than re-saving it from Sketch.

Icon is displaying properly, but is the wrong color (or contains pieces that are the wrong color)

You may have missed a fill property declaration within the SVG. Go back into the SVG file in your text editor of choice and cmd+F to find any fill properties you might have missed, and replace them with currentColor.

Icon is not displaying at all

Make sure that your icon is named correctly in your HTML or CSS.

If it’s a custom icon, make sure that the #custom-- piece is in the HTML, and/or make sure that the /custom/ subfolder is included in CSS where you’re calling it.

If it’s a bootstrap default icon, make sure that you added the icon to your gulpfile and ran npm install in iTerm.

If you’re trying to use a bootstrap default icon and getting an error when you run gulp, even though you know it’s named correctly, and you have everything else correct, it may be that the icon you’re using is new enough that it shows up on the Bootstrap website, but wasn’t included when you first installed NPM on the project. So it’s not being pulled in/updated when you try to run npm install normally. To fix this, you can simply install NPM fresh–delete the node_modules folder and package-lock.json and run a fresh NPM install.

If an icon from the bootstrap set is smaller than you expect when you set the iconSize mixin, this is because they have intentionally set the icon to be smaller than its canvas size. The canvas size is what gets set by the iconSize mixin. You can experiment with the iconSize to see what makes the icon be sized correctly, or you can simply create a custom version of the icon from the Sketch files to skip the trial-and-error.

Example Sites

Tags: icons, gulp, bootstrap, iconfont