npm package: @kudog/nuxt-bootstrap-icons
Description: A Nuxt module that automatically integrates Bootstrap Icons with font support
Author: kudog
Latest version: 1.0.4

# @kudog/nuxt-bootstrap-icons | Bootstrap Icons Nuxt Module | Bootstrap 图标 Nuxt 模块

[![npm version][npm-version-src]][npm-version-href]
[![npm downloads][npm-downloads-src]][npm-downloads-href]
[![License][license-src]][license-href]
[![Nuxt][nuxt-src]][nuxt-href]

[English](#english) | [中文](#中文)

---

## English

A Nuxt module that automatically integrates Bootstrap Icons into your Nuxt 4 application with font support.

- [✨ &nbsp;Release Notes](/CHANGELOG.md)
<!-- - [🏀 Online playground](https://stackblitz.com/github/your-org/my-module?file=playground%2Fapp.vue) -->
<!-- - [📖 &nbsp;Documentation](https://example.com) -->

### Features

- 🎨 &nbsp;**Auto CSS Injection**: Automatically includes Bootstrap Icons font CSS
- ⚡ &nbsp;**Zero Configuration**: Works out of the box with sensible defaults
- 🎯 &nbsp;**Official Syntax**: Use the same syntax as official Bootstrap Icons
- 🔧 &nbsp;**Configurable**: Enable/disable the module as needed
- 📦 &nbsp;**Font Support**: Uses `bootstrap-icons/font/bootstrap-icons.css` for better performance
- 🎛️ &nbsp;**Size Control**: Multiple ways to control icon sizes

### Quick Setup

Install the module to your Nuxt application:

```bash
# Install the module
npm install @kudog/nuxt-bootstrap-icons

# Or install bootstrap-icons directly if needed
npm install bootstrap-icons
```

Add to your `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  modules: ['@kudog/nuxt-bootstrap-icons']
})
```

That's it! You can now use Bootstrap Icons in your Nuxt app ✨

### Usage

#### Basic Configuration

Add the module to your `nuxt.config.ts`:

```typescript
export default defineNuxtConfig({
  modules: ['@kudog/nuxt-bootstrap-icons'],
  bootstrapIcons: {
    enabled: true // default: true
  }
})
```

#### Using Icons in Templates

Once configured, you can use Bootstrap Icons anywhere in your templates using the official syntax:

```vue
<template>
  <div>
    <!-- Basic icons -->
    <i class="bi bi-heart"></i>
    <i class="bi bi-star"></i>
    <i class="bi bi-house"></i>
    
    <!-- Filled icons -->
    <i class="bi bi-heart-fill"></i>
    <i class="bi bi-star-fill"></i>
    
    <!-- NEW: Simple size attribute (recommended) -->
    <i class="bi bi-bag-check" size="24"></i>
    <i class="bi bi-heart" size="32"></i>
    <i class="bi bi-star" size="48"></i>
  </div>
</template>
```

#### Icon Size Control

There are multiple ways to control the size of Bootstrap Icons:

**🆕 NEW: Using Size Attribute (Recommended):**
```vue
<template>
  <div>
    <!-- Simple and clean syntax -->
    <i class="bi bi-heart" size="16"></i>   <!-- 16px -->
    <i class="bi bi-heart" size="24"></i>   <!-- 24px -->
    <i class="bi bi-heart" size="32"></i>   <!-- 32px -->
    <i class="bi bi-heart" size="48"></i>   <!-- 48px -->
    
    <!-- Works with any Bootstrap Icon -->
    <i class="bi bi-bag-check" size="20"></i>
    <i class="bi bi-star-fill" size="28"></i>
    <i class="bi bi-house-fill" size="36"></i>
  </div>
</template>
```

**1. Using CSS Font Size:**
```vue
<template>
  <div>
    <!-- Using inline styles (CORRECT way) -->
    <i class="bi bi-heart" style="font-size: 16px;"></i>  <!-- 16px -->
    <i class="bi bi-heart" style="font-size: 24px;"></i>  <!-- 24px -->
    <i class="bi bi-heart" style="font-size: 32px;"></i>  <!-- 32px -->
    
    <!-- Using rem units -->
    <i class="bi bi-house" style="font-size: 1rem;"></i>   <!-- 16px -->
    <i class="bi bi-house" style="font-size: 1.5rem;"></i> <!-- 24px -->
    <i class="bi bi-house" style="font-size: 2rem;"></i>   <!-- 32px -->
    
    <!-- Using CSS classes -->
    <i class="bi bi-heart small-icon"></i>
    <i class="bi bi-heart medium-icon"></i>
    <i class="bi bi-heart large-icon"></i>
  </div>
</template>

<style>
.small-icon { font-size: 14px; }   /* or 0.875rem */
.medium-icon { font-size: 20px; }  /* or 1.25rem */
.large-icon { font-size: 32px; }   /* or 2rem */
</style>
```

**❌ INCORRECT Usage:**
```vue
<!-- This is WRONG - font-size is not a valid HTML attribute -->
<i class="bi bi-house" font-size="24"></i>
```

**✅ CORRECT Usage:**
```vue
<!-- Use style attribute instead -->
<i class="bi bi-house" style="font-size: 24px;"></i>
```

**2. Using Tailwind CSS (if available):**
```vue
<template>
  <div>
    <i class="bi bi-heart text-sm"></i>   <!-- 14px -->
    <i class="bi bi-heart text-base"></i> <!-- 16px -->
    <i class="bi bi-heart text-lg"></i>   <!-- 18px -->
    <i class="bi bi-heart text-xl"></i>   <!-- 20px -->
    <i class="bi bi-heart text-2xl"></i>  <!-- 24px -->
    <i class="bi bi-heart text-3xl"></i>  <!-- 30px -->
    <i class="bi bi-heart text-4xl"></i>  <!-- 36px -->
  </div>
</template>
```

**3. Using Bootstrap Classes (if Bootstrap CSS is available):**
```vue
<template>
  <div>
    <i class="bi bi-heart fs-6"></i> <!-- Small -->
    <i class="bi bi-heart fs-5"></i> <!-- Default -->
    <i class="bi bi-heart fs-4"></i> <!-- Large -->
    <i class="bi bi-heart fs-3"></i> <!-- Extra Large -->
    <i class="bi bi-heart fs-2"></i> <!-- XXL -->
    <i class="bi bi-heart fs-1"></i> <!-- XXXL -->
  </div>
</template>
```

#### Available Icons

This module includes all Bootstrap Icons. You can find the complete list and search for icons at:
- [Official Bootstrap Icons](https://icons.getbootstrap.com/)

#### Configuration Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `enabled` | `boolean` | `true` | Enable/disable the Bootstrap Icons integration |

#### Examples

```vue
<template>
  <div>
    <!-- Navigation -->
    <i class="bi bi-arrow-left"></i>
    <i class="bi bi-arrow-right"></i>
    
    <!-- Actions -->
    <i class="bi bi-plus-circle"></i>
    <i class="bi bi-trash"></i>
    <i class="bi bi-pencil"></i>
    
    <!-- Communication -->
    <i class="bi bi-envelope"></i>
    <i class="bi bi-telephone"></i>
    <i class="bi bi-chat"></i>
    
    <!-- Files -->
    <i class="bi bi-file-text"></i>
    <i class="bi bi-file-image"></i>
    <i class="bi bi-download"></i>
    
    <!-- With colors and sizes -->
    <i class="bi bi-heart" style="color: red; font-size: 2rem;"></i>
    <i class="bi bi-star" style="color: gold; font-size: 1.5rem;"></i>
  </div>
</template>
```

---

## 中文

一个自动将 Bootstrap Icons 集成到 Nuxt 4 应用程序中的模块，支持字体文件。

### 特性

- 🎨 &nbsp;**自动 CSS 注入**: 自动包含 Bootstrap Icons 字体 CSS
- ⚡ &nbsp;**零配置**: 开箱即用，具有合理的默认设置
- 🎯 &nbsp;**官方语法**: 使用与官方 Bootstrap Icons 相同的语法
- 🔧 &nbsp;**可配置**: 根据需要启用/禁用模块
- 📦 &nbsp;**字体支持**: 使用 `bootstrap-icons/font/bootstrap-icons.css` 以获得更好的性能
- 🎛️ &nbsp;**大小控制**: 多种方式控制图标大小

### 快速开始

安装模块到你的 Nuxt 应用程序：

```bash
# 安装模块
npm install @kudog/nuxt-bootstrap-icons

# 或者直接安装 bootstrap-icons（如果需要）
npm install bootstrap-icons
```

添加到你的 `nuxt.config.ts`：

```typescript
export default defineNuxtConfig({
  modules: ['@kudog/nuxt-bootstrap-icons']
})
```

就是这样！现在你可以在 Nuxt 应用中使用 Bootstrap Icons 了 ✨

### 使用方法

#### 基本配置

在你的 `nuxt.config.ts` 中添加模块：

```typescript
export default defineNuxtConfig({
  modules: ['@kudog/nuxt-bootstrap-icons'],
  bootstrapIcons: {
    enabled: true // 默认值: true
  }
})
```

#### 在模板中使用图标

配置完成后，你可以在模板中的任何地方使用官方语法来使用 Bootstrap Icons：

```vue
<template>
  <div>
    <!-- 基础图标 -->
    <i class="bi bi-heart"></i>
    <i class="bi bi-star"></i>
    <i class="bi bi-house"></i>
    
    <!-- 填充图标 -->
    <i class="bi bi-heart-fill"></i>
    <i class="bi bi-star-fill"></i>
    
    <!-- 新功能：简单的 size 属性（推荐） -->
    <i class="bi bi-bag-check" size="24"></i>
    <i class="bi bi-heart" size="32"></i>
    <i class="bi bi-star" size="48"></i>
  </div>
</template>
```

#### 图标大小控制

有多种方式来控制 Bootstrap Icons 的大小：

**🆕 新功能：使用 Size 属性（推荐）：**
```vue
<template>
  <div>
    <!-- 简洁清晰的语法 -->
    <i class="bi bi-heart" size="16"></i>   <!-- 16px -->
    <i class="bi bi-heart" size="24"></i>   <!-- 24px -->
    <i class="bi bi-heart" size="32"></i>   <!-- 32px -->
    <i class="bi bi-heart" size="48"></i>   <!-- 48px -->
    
    <!-- 适用于任何 Bootstrap 图标 -->
    <i class="bi bi-bag-check" size="20"></i>
    <i class="bi bi-star-fill" size="28"></i>
    <i class="bi bi-house-fill" size="36"></i>
  </div>
</template>
```

**1. 使用 CSS 字体大小：**
```vue
<template>
  <div>
    <!-- 使用内联样式（正确方式） -->
    <i class="bi bi-heart" style="font-size: 16px;"></i>  <!-- 16px -->
    <i class="bi bi-heart" style="font-size: 24px;"></i>  <!-- 24px -->
    <i class="bi bi-heart" style="font-size: 32px;"></i>  <!-- 32px -->
    
    <!-- 使用 rem 单位 -->
    <i class="bi bi-house" style="font-size: 1rem;"></i>   <!-- 16px -->
    <i class="bi bi-house" style="font-size: 1.5rem;"></i> <!-- 24px -->
    <i class="bi bi-house" style="font-size: 2rem;"></i>   <!-- 32px -->
    
    <!-- 使用 CSS 类 -->
    <i class="bi bi-heart small-icon"></i>
    <i class="bi bi-heart medium-icon"></i>
    <i class="bi bi-heart large-icon"></i>
  </div>
</template>

<style>
.small-icon { font-size: 14px; }   /* 或 0.875rem */
.medium-icon { font-size: 20px; }  /* 或 1.25rem */
.large-icon { font-size: 32px; }   /* 或 2rem */
</style>
```

**❌ 错误用法：**
```vue
<!-- 这是错误的 - font-size 不是有效的 HTML 属性 -->
<i class="bi bi-house" font-size="24"></i>
```

**✅ 正确用法：**
```vue
<!-- 使用 style 属性 -->
<i class="bi bi-house" style="font-size: 24px;"></i>
```

**2. 使用 Tailwind CSS（如果可用）：**
```vue
<template>
  <div>
    <i class="bi bi-heart text-sm"></i>   <!-- 14px -->
    <i class="bi bi-heart text-base"></i> <!-- 16px -->
    <i class="bi bi-heart text-lg"></i>   <!-- 18px -->
    <i class="bi bi-heart text-xl"></i>   <!-- 20px -->
    <i class="bi bi-heart text-2xl"></i>  <!-- 24px -->
    <i class="bi bi-heart text-3xl"></i>  <!-- 30px -->
    <i class="bi bi-heart text-4xl"></i>  <!-- 36px -->
  </div>
</template>
```

**3. 使用 Bootstrap 类（如果 Bootstrap CSS 可用）：**
```vue
<template>
  <div>
    <i class="bi bi-heart fs-6"></i> <!-- 小 -->
    <i class="bi bi-heart fs-5"></i> <!-- 默认 -->
    <i class="bi bi-heart fs-4"></i> <!-- 大 -->
    <i class="bi bi-heart fs-3"></i> <!-- 特大 -->
    <i class="bi bi-heart fs-2"></i> <!-- 超大 -->
    <i class="bi bi-heart fs-1"></i> <!-- 极大 -->
  </div>
</template>
```

#### 可用图标

此模块包含所有 Bootstrap Icons。你可以在以下网站找到完整列表并搜索图标：
- [官方 Bootstrap Icons](https://icons.getbootstrap.com/)

#### 配置选项

| 选项 | 类型 | 默认值 | 描述 |
|------|------|--------|------|
| `enabled` | `boolean` | `true` | 启用/禁用 Bootstrap Icons 集成 |

#### 示例

```vue
<template>
  <div>
    <!-- 导航 -->
    <i class="bi bi-arrow-left"></i>
    <i class="bi bi-arrow-right"></i>
    
    <!-- 操作 -->
    <i class="bi bi-plus-circle"></i>
    <i class="bi bi-trash"></i>
    <i class="bi bi-pencil"></i>
    
    <!-- 通信 -->
    <i class="bi bi-envelope"></i>
    <i class="bi bi-telephone"></i>
    <i class="bi bi-chat"></i>
    
    <!-- 文件 -->
    <i class="bi bi-file-text"></i>
    <i class="bi bi-file-image"></i>
    <i class="bi bi-download"></i>
    
    <!-- 带颜色和大小 -->
    <i class="bi bi-heart" style="color: red; font-size: 2rem;"></i>
    <i class="bi bi-star" style="color: gold; font-size: 1.5rem;"></i>
  </div>
</template>
```

---

## Contribution

<details>
  <summary>Local development</summary>
  
  ```bash
  # Install dependencies
  npm install
  
  # Generate type stubs
  npm run dev:prepare
  
  # Develop with the playground
  npm run dev
  
  # Build the playground
  npm run dev:build
  
  # Run ESLint
  npm run lint
  
  # Run Vitest
  npm run test
  npm run test:watch
  
  # Release new version
  npm run release
  ```

</details>


<!-- Badges -->
[npm-version-src]: https://img.shields.io/npm/v/@kudog/nuxt-bootstrap-icons/latest.svg?style=flat&colorA=020420&colorB=00DC82
[npm-version-href]: https://npmjs.com/package/@kudog/nuxt-bootstrap-icons

[npm-downloads-src]: https://img.shields.io/npm/dm/@kudog/nuxt-bootstrap-icons.svg?style=flat&colorA=020420&colorB=00DC82
[npm-downloads-href]: https://npm.chart.dev/@kudog/nuxt-bootstrap-icons

[license-src]: https://img.shields.io/npm/l/@kudog/nuxt-bootstrap-icons.svg?style=flat&colorA=020420&colorB=00DC82
[license-href]: https://npmjs.com/package/@kudog/nuxt-bootstrap-icons

[nuxt-src]: https://img.shields.io/badge/Nuxt-020420?logo=nuxt.js
[nuxt-href]: https://nuxt.com