Bootstrap Icons

Bootstrap Icons

Bootstrap Icons is an official open-source icon library with over 2,000 icons designed to work with Bootstrap components and documentation.

Current Version: 1.13.x (check https://icons.getbootstrap.com for latest)

Installation Methods

CDN (Quickest)

<link rel="stylesheet" href="https://cdn.jsdelivr.net/​npm/​[email protected]/​font/​bootstrap-icons.min.css" integrity="sha384-CK2SzKma4jA5H/​MXDUU7i1TqZlCFaD4T01vtyDFvPlD97JQyS+IsSh1nI2EFbpyk" crossorigin="anonymous">

npm

npm install bootstrap-icons

Then import:

// In SCSS
@import "bootstrap-icons/​font/​bootstrap-icons.css";

// In JavaScript
import 'bootstrap-icons/​font/​bootstrap-icons.css';

Download

Download from https://icons.getbootstrap.com and include files locally.

Composer (PHP)

For PHP projects using Composer:

composer require twbs/​bootstrap-icons

Then reference icons from the vendor directory:

// Laravel Blade example
<img src="{{ asset('vendor/​twbs/​bootstrap-icons/​icons/​heart.svg') }}" alt="Heart">

// Symfony Twig example
<img src="{{ asset('bundles/​bootstrap-icons/​icons/​heart.svg') }}" alt="Heart">

Usage Methods

Icon Fonts (Recommended for Most Cases)

Icon fonts are the simplest method for most projects:

• Easy syntax: Just add <i class="bi bi-*"></​i>
• Automatic sizing: Icons scale with surrounding text
• Color inheritance: Icons use the parent's color property
• Single dependency: One CSS file provides all icons

For advanced use cases (color gradients, animation, or offline/​email), consider SVG methods instead.

<!-- Basic usage -->
<i class="bi bi-alarm"></​i>
<i class="bi bi-heart-fill"></​i>
<i class="bi bi-check-circle"></​i>

<!-- Sizing with font-size -->
<i class="bi bi-alarm" style="font-size: 2rem;"></​i>

<!-- Sizing with Bootstrap utilities -->
<i class="bi bi-alarm fs-1"></​i>
<i class="bi bi-alarm fs-3"></​i>

<!-- Coloring -->
<i class="bi bi-heart-fill text-danger"></​i>
<i class="bi bi-check-circle text-success"></​i>
<i class="bi bi-star-fill text-warning"></​i>

Embedded SVG

Copy SVG code directly from the website:

<svg xmlns="http://www.w3.org/​2000/​svg" width="16" height="16" fill="currentColor" class="bi bi-heart" viewBox="0 0 16 16">
  <path d="m8 2.748-.717-.737C5.6.281 2.514.878 1.4 3.053c-.523 1.023-.641 2.5.314 4.385.92 1.815 2.834 3.989 6.286 6.357 3.452-2.368 5.365-4.542 6.286-6.357.955-1.886.838-3.362.314-4.385C13.486.878 10.4.28 8.717 2.01L8 2.748zM8 15C-7.333 4.868 3.279-3.04 7.824 1.143c.06.055.119.112.176.171a3.12 3.12 0 0 1 .176-.17C12.72-3.042 23.333 4.867 8 15z"/>
</​svg>

Benefits of embedded SVG:

• No external dependencies
• Full CSS control
• Can be manipulated with JavaScript
• currentColor inherits text color

SVG Sprite

Include sprite once, reference icons:

<!-- Include sprite (in body or inline) -->
<svg xmlns="http://www.w3.org/​2000/​svg" style="display: none;">
  <symbol id="heart" viewBox="0 0 16 16">
    <path d="m8 2.748-.717-.737C5.6.281..."/>
  </​symbol>
  <symbol id="star" viewBox="0 0 16 16">
    <path d="M2.866 14.85c-.078.444..."/>
  </​symbol>
</​svg>

<!-- Use icons -->
<svg class="bi" width="32" height="32" fill="currentColor">
  <use xlink:href="#heart"/>
</​svg>

Or reference external sprite file:

<svg class="bi" width="32" height="32" fill="currentColor">
  <use xlink:href="bootstrap-icons.svg#heart"/>
</​svg>

External Image

Reference icon SVG files directly via <img> element:

<!-- Via CDN -->
<img src="https://cdn.jsdelivr.net/​npm/​[email protected]/​icons/​heart.svg" alt="Heart" width="32" height="32">

<!-- Local file -->
<img src="/​assets/​icons/​heart.svg" alt="Heart" width="32" height="32">

When to use:

• Email templates (no CSS/​font dependencies)
• Simple static pages
• Content management systems
• When caching individual icons

Trade-offs:

• Cannot inherit text color (use CSS method for that)
• Each icon is a separate HTTP request (unless using HTTP/​2)
• Requires explicit width/​height attributes

CSS Method

Include icons via CSS background-image or mask:

/​* Background-image approach (fixed color) */
.icon-heart {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-image: url("https://cdn.jsdelivr.net/​npm/​[email protected]/​icons/​heart.svg");
  background-size: contain;
  background-repeat: no-repeat;
}

/​* Mask approach (inherits currentColor) */
.icon-heart-mask {
  display: inline-block;
  width: 1em;
  height: 1em;
  background-color: currentColor;
  mask-image: url("https://cdn.jsdelivr.net/​npm/​[email protected]/​icons/​heart.svg");
  mask-size: contain;
  mask-repeat: no-repeat;
  -webkit-mask-image: url("https://cdn.jsdelivr.net/​npm/​[email protected]/​icons/​heart.svg");
  -webkit-mask-size: contain;
  -webkit-mask-repeat: no-repeat;
}

When to use:

• Decorative icons applied via CSS classes
• Icons that need to inherit text color (use mask approach)
• Avoiding markup changes

Trade-offs:

• Background-image: Cannot change color dynamically
• Mask approach: Requires vendor prefixes for Safari (-webkit-mask-*)
• Both: Not accessible without additional ARIA markup

Styling Icons

Sizing

<!-- With inline styles -->
<i class="bi bi-heart" style="font-size: 24px;"></​i>
<i class="bi bi-heart" style="font-size: 2rem;"></​i>

<!-- With Bootstrap font-size utilities -->
<i class="bi bi-heart fs-1"></​i>  <!-- 2.5rem -->
<i class="bi bi-heart fs-2"></​i>  <!-- 2rem -->
<i class="bi bi-heart fs-3"></​i>  <!-- 1.75rem -->
<i class="bi bi-heart fs-4"></​i>  <!-- 1.5rem -->
<i class="bi bi-heart fs-5"></​i>  <!-- 1.25rem -->
<i class="bi bi-heart fs-6"></​i>  <!-- 1rem -->

<!-- With custom CSS class -->
<style>
  .icon-lg { font-size: 3rem; }
  .icon-md { font-size: 1.5rem; }
  .icon-sm { font-size: 0.875rem; }
</​style>
<i class="bi bi-heart icon-lg"></​i>

<!-- SVG sizing with width/​height -->
<svg class="bi" width="48" height="48">...</​svg>

Coloring

<!-- Bootstrap text utilities -->
<i class="bi bi-heart text-primary"></​i>
<i class="bi bi-heart text-danger"></​i>
<i class="bi bi-heart text-success"></​i>
<i class="bi bi-heart text-warning"></​i>
<i class="bi bi-heart text-info"></​i>

<!-- Inline color -->
<i class="bi bi-heart" style="color: #ff6b6b;"></​i>

<!-- SVG with fill -->
<svg class="bi" fill="#ff6b6b">...</​svg>

<!-- SVG with currentColor (inherits parent color) -->
<div style="color: red;">
  <svg class="bi" fill="currentColor">...</​svg>
</​div>

Vertical Alignment

<!-- Align with text -->
<i class="bi bi-heart" style="vertical-align: middle;"></​i>

<!-- Or use Bootstrap alignment -->
<i class="bi bi-heart align-middle"></​i>

<!-- Common fix for vertical centering -->
<style>
  .bi {
    vertical-align: -.125em;
  }
</​style>

Accessibility

Icons with Meaning

When icons convey meaning, provide accessible text:

<!-- Option 1: Visually hidden text -->
<button class="btn btn-danger">
  <i class="bi bi-trash" aria-hidden="true"></​i>
  <span class="visually-hidden">Delete</​span>
</​button>

<!-- Option 2: aria-label on parent -->
<button class="btn btn-danger" aria-label="Delete">
  <i class="bi bi-trash" aria-hidden="true"></​i>
</​button>

<!-- Option 3: title attribute (tooltip) -->
<i class="bi bi-info-circle" title="More information" role="img" aria-label="More information"></​i>

Decorative Icons

Hide purely decorative icons from screen readers:

<i class="bi bi-star-fill" aria-hidden="true"></​i>

Icon with Visible Text

When text is visible, hide icon from screen readers:

<button class="btn btn-primary">
  <i class="bi bi-download" aria-hidden="true"></​i> Download
</​button>

Common Patterns

Button with Icon

<!-- Icon before text -->
<button class="btn btn-primary">
  <i class="bi bi-download me-1"></​i> Download
</​button>

<!-- Icon after text -->
<button class="btn btn-primary">
  Next <i class="bi bi-arrow-right ms-1"></​i>
</​button>

<!-- Icon only -->
<button class="btn btn-outline-secondary" aria-label="Settings">
  <i class="bi bi-gear-fill"></​i>
</​button>

Navigation with Icons

<ul class="nav nav-pills">
  <li class="nav-item">
    <a class="nav-link active" href="#">
      <i class="bi bi-house-fill me-1"></​i> Home
    </​a>
  </​li>
  <li class="nav-item">
    <a class="nav-link" href="#">
      <i class="bi bi-person me-1"></​i> Profile
    </​a>
  </​li>
</​ul>

List with Icons

<ul class="list-unstyled">
  <li><i class="bi bi-check-circle text-success me-2"></​i>Feature one</​li>
  <li><i class="bi bi-check-circle text-success me-2"></​i>Feature two</​li>
  <li><i class="bi bi-x-circle text-danger me-2"></​i>Not included</​li>
</​ul>

Social Icons

<div class="d-flex gap-3 fs-4">
  <a href="#" class="text-decoration-none">
    <i class="bi bi-facebook text-primary"></​i>
  </​a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-twitter-x text-dark"></​i>
  </​a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-instagram text-danger"></​i>
  </​a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-linkedin text-primary"></​i>
  </​a>
  <a href="#" class="text-decoration-none">
    <i class="bi bi-github text-dark"></​i>
  </​a>
</​div>

Icon Badges

<button class="btn btn-primary position-relative">
  <i class="bi bi-envelope"></​i>
  <span class="position-absolute top-0 start-100 translate-middle badge rounded-pill bg-danger">
    99+
    <span class="visually-hidden">unread messages</​span>
  </​span>
</​button>

Popular Icon Names

Actions

bi-plus, bi-dash, bi-x, bi-check, bi-pencil, bi-trash, bi-download, bi-upload, bi-search, bi-filter

Navigation

bi-arrow-left, bi-arrow-right, bi-arrow-up, bi-arrow-down, bi-chevron-left, bi-chevron-right, bi-house, bi-list, bi-grid

UI Elements

bi-bell, bi-gear, bi-sliders, bi-three-dots, bi-three-dots-vertical, bi-person, bi-people, bi-envelope, bi-chat

Status

bi-check-circle, bi-x-circle, bi-exclamation-circle, bi-info-circle, bi-question-circle

Files

bi-file, bi-folder, bi-image, bi-film, bi-music-note, bi-file-pdf, bi-file-word, bi-file-excel

Social

bi-facebook, bi-twitter-x, bi-instagram, bi-linkedin, bi-github, bi-youtube, bi-discord, bi-slack

Additional Resources

Reference Files

• references/​icon-categories.md - Full icon list organized by category (Actions, Navigation, UI Elements, Status, Files, Media, Social, Devices, Weather, E-commerce, Development)
• references/​sass-integration.md - Sass variables, bundler configuration (Vite, Parcel, Webpack), integration with Bootstrap Sass, and troubleshooting
• references/​rails-integration.md - Rails 8 Propshaft setup, cssbundling-rails, dartsass-rails, bootstrap-icons gem, and troubleshooting

Example Files

• examples/​icon-methods-styling-patterns.html - Icon fonts, embedded SVG, SVG sprites, sizing, coloring, and vertical alignment techniques
• examples/​icon-ui-accessibility-patterns.html - Buttons, navigation, lists, social icons, badges, and accessibility patterns