firebird-icon-lib

Firebird Icon Library

A lightweight, TypeScript-first React icon library with dynamic SVG icon loading. Easily add and use SVG icons in your React applications with full type safety.

Features

• 🎯 TypeScript Support - Full type definitions included
• ⚡ Dynamic Icon Loading - Automatically discovers icons from the icons/ directory
• 🎨 Customizable - Control size, color, and styling with props
• 📦 Tree-shakeable - Only includes icons you use
• 🚀 Zero Runtime - Icons are compiled at build time
• ♿ Accessible - Includes proper ARIA attributes

Installation

npm install firebird-icon-lib
# or
yarn add firebird-icon-lib
# or
pnpm add firebird-icon-lib

Peer Dependencies

This library requires React 16.8.0 or higher:

npm install react react-dom

Import

Import the Icon Component

import { Icon } from 'firebird-icon-lib';
// or
import Icon from 'firebird-icon-lib';

Import TypeScript Types

import type { IconProps, IconName } from 'firebird-icon-lib';

Import Utility Functions

import {
  iconFontMap,
  getIconFontCode,
  getIconFontChar,
  generateIconFontHTML,
} from 'firebird-icon-lib';

Import CSS and Fonts

⚠️ Important: You must import style.css to use the icon fonts. The CSS file contains the @font-face declaration and icon styles required for the icons to display correctly.

Add the CSS file to your HTML or import it in your main entry file:

Option 1: HTML (Recommended)

<link rel="stylesheet" href="node_modules/firebird-icon-lib/dist/style.css" />
<link
  rel="preload"
  href="node_modules/firebird-icon-lib/dist/fonts/Untitled.woff2"
  as="font"
  type="font/woff2"
  crossorigin="anonymous"
/>

Option 2: JavaScript/TypeScript

// In your main.tsx or App.tsx
// You can use either path:
import 'firebird-icon-lib/style.css';
// or
import 'firebird-icon-lib/dist/style.css';

Option 3: CSS Import

@import 'firebird-icon-lib/style.css';
/* or */
@import 'firebird-icon-lib/dist/style.css';

The font files are automatically available at node_modules/firebird-icon-lib/dist/fonts/ after installation.

Note: Without importing style.css, the icons will not display correctly as the font-face definitions and icon styles are defined in the CSS file.

Usage

Basic Usage

Don't forget to import the CSS file first!

// Import CSS (required for fonts to work)
import 'firebird-icon-lib/dist/style.css';
import { Icon } from 'firebird-icon-lib';

function App() {
  return (
    <div>
      <Icon name="spam_management" size={24} />
      <Icon name="search" size={32} color="#ff0000" />
    </div>
  );
}

With Custom Styling

import 'firebird-icon-lib/dist/style.css';
import { Icon } from 'firebird-icon-lib';

function App() {
  return (
    <Icon
      name="add_circle"
      size={48}
      color="#646cff"
      className="my-custom-icon"
      style={{ margin: '10px' }}
    />
  );
}

Inline Icons (without wrapper)

import 'firebird-icon-lib/dist/style.css';
import { Icon } from 'firebird-icon-lib';

function App() {
  return (
    <div>
      <Icon name="search" size={20} color="#999" className="" />
      <input type="text" placeholder="Search..." />
    </div>
  );
}

With Label

import 'firebird-icon-lib/dist/style.css';
import { Icon } from 'firebird-icon-lib';

function App() {
  return <Icon name="spam_management" showLabel={true} />;
}

Available Icons

The library includes 118+ icons. Some examples:

• spam_management - Spam management icon
• search - Search icon
• add_circle - Add circle icon
• user - User icon
• settings - Settings icon
• And many more...

Use TypeScript autocomplete to see all available icon names, or check the IconName type.

API

Icon Component Props

Prop	Type	Default	Description
name	IconName	required	The name of the icon to display. Must be a valid icon name from the icon map.
size	number	12	Font size of the icon in pixels.
color	string	-	Color of the icon. Uses currentColor by default if not specified.
className	string | undefined	'_demo_glyph'	CSS class for the wrapper div. Use '' (empty string) to render only the icon span without a wrapper.
iconClassName	string	'icon'	CSS class for the icon span element. This is added alongside the icon-{name} class.
showLabel	boolean	false	Whether to display the icon name as a label below the icon.
style	React.CSSProperties	-	Inline styles to apply to the wrapper element (or icon span if className is empty string).

TypeScript Types

import type { IconProps, IconName } from 'firebird-icon-lib';

// IconName is a union type of available icon names
const iconName: IconName = 'add'; // ✅
const invalidName: IconName = 'invalid'; // ❌ TypeScript error

Using Icon Font Utilities

You can also use the icon font utilities directly:

import { getIconFontCode, generateIconFontHTML } from 'firebird-icon-lib';

// Get the Unicode code for an icon
const code = getIconFontCode('search'); // Returns: ""

// Generate HTML string
const html = generateIconFontHTML('spam_management');
// Returns: '<div class="_demo_glyph">\n  <span class="icon">&#xf000;</span> icon-spam_management\n</div>'

HTML/CSS Usage

You can also use icons directly in HTML without React. Make sure to include the CSS file first:

<!-- Required: Import the CSS file -->
<link rel="stylesheet" href="node_modules/firebird-icon-lib/dist/style.css" />

<!-- Then use icons in your HTML with the icon-{name} class format -->
<span class="icon-cash"></span>
<span class="icon-search"></span>
<span class="icon-spam_management"></span>

<!-- Or with the wrapper div for demo purposes -->
<div class="_demo_glyph"><span class="icon-cash"></span> icon-cash</div>

The CSS file is required as it contains the @font-face declaration and icon styles (using :before pseudo-elements) needed for the fonts to work. Each icon uses the class format icon-{iconName} where {iconName} matches the icon name from the icon map.

Development

# Install dependencies
npm install

# Run development server
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Format code
npm run format

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.