Tawseel 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 tawseel-icon-lib
# or
yarn add tawseel-icon-lib
# or
pnpm add tawseel-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 'tawseel-icon-lib';
// or
import Icon from 'tawseel-icon-lib';

Import TypeScript Types

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

Import Utility Functions

import {
  iconFontMap,
  getIconFontCode,
  getIconFontChar,
  generateIconFontHTML,
} from 'tawseel-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/tawseel-icon-lib/dist/style.css" />
<link
  rel="preload"
  href="node_modules/tawseel-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 'tawseel-icon-lib/style.css';
// or
import 'tawseel-icon-lib/dist/style.css';

Option 3: CSS Import

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

The font files are automatically available at node_modules/tawseel-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 'tawseel-icon-lib/dist/style.css';
import { Icon } from 'tawseel-icon-lib';

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

With Custom Styling

import 'tawseel-icon-lib/dist/style.css';
import { Icon } from 'tawseel-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 'tawseel-icon-lib/dist/style.css';
import { Icon } from 'tawseel-icon-lib';

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

With Label

import 'tawseel-icon-lib/dist/style.css';
import { Icon } from 'tawseel-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 'tawseel-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 'tawseel-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/tawseel-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.