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