npm package: @freightos/icons
Description: A comprehensive icon library for Freightos applications with full TypeScript support
Author: Jiries Nasrawi
Latest version: 3.0.1

# @freightos/icons

A comprehensive icon library with 280 SVG icons designed for Freightos applications. Built with React, TypeScript, and developer experience in mind.

This package lives inside the [FreightWind](https://freightwind.freightos.com) monorepo at `packages/icons/`.

## Features

- 🎨 **280 Icons** - Complete set of professionally designed icons
- 📦 **Tree-shakeable** - Import only what you need
- 🔷 **TypeScript First** - Full type definitions included
- ⚡ **Dual Format** - Both ESM and CJS builds included
- 🎯 **Semantic Sizing** - Use `xs` (12px), `sm` (16px), `md` (24px), `lg` (32px) or any number/string
- 🎨 **Themeable** - Uses `currentColor` by default for easy theming
- ♿ **Accessible** - Proper ARIA support via SVG props
- 🪶 **Lightweight** - Individual icons are tiny
- ⚛️ **React 16.8+** - Works with hooks and modern React

## Installation

```bash
npm install @freightos/icons
# or
yarn add @freightos/icons
# or
pnpm add @freightos/icons
```

> **Monorepo users:** Within the FreightWind repo, icons are linked via `workspace:*` — no install needed.

## Usage Guide

### Basic Usage

Import icons directly from the package:

```tsx
import { IconSearch, IconUser, IconDashboard } from '@freightos/icons';

function MyComponent() {
  return (
    <div>
      <IconSearch size={24} />
      <IconUser color="blue" />
      <IconDashboard className="my-icon" />
    </div>
  );
}
```

### Props

All icons accept the following props:

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `size` | `IconSize \| number \| string` | `'1em'` | Width and height — semantic tokens (`xs`, `sm`, `md`, `lg`), pixel numbers, or CSS strings |
| `color` | `FreightosColor \| string` | `'currentColor'` | Color of the icon - supports design system colors with autocomplete or any CSS color value |
| `className` | `string` | - | Additional CSS classes |
| `...props` | `SVGProps<SVGSVGElement>` | - | Any valid SVG attributes |

### Sizing

Icons are responsive by default and scale with the parent font size. You can customize the size in multiple ways:

```tsx
// Default size (1em - scales with font-size)
<IconSearch />

// Numeric size (pixels)
<IconSearch size={24} />
<IconSearch size={32} />

// String size (CSS units)
<IconSearch size="2rem" />
<IconSearch size="24px" />

// Responsive with parent font-size
<div className="text-lg">
  <IconSearch /> {/* Icon automatically scales */}
</div>

// Using CSS classes (Tailwind example)
<IconSearch className="w-6 h-6" />
```

### Coloring

Icons use `currentColor` by default, making them easy to theme. The `color` prop supports Freightos design system colors with autocomplete, plus any CSS color value:

```tsx
// Freightos design system colors (with autocomplete!)
<IconSearch color="blue" />
<IconError color="red" />
<IconWarning color="yellow" />
<IconSuccess color="green" />

// Inherits parent text color
<div className="text-blue-500">
  <IconSearch />
</div>

// Any CSS color value
<IconSearch color="#1890ff" />
<IconSearch color="var(--primary-color)" />

// Using CSS classes
<IconSearch className="text-blue-500" />
<IconSearch className="text-gray-900 dark:text-white" />
```

#### Available Design System Colors

The following Freightos design system colors are available with autocomplete support:

**Blues:** `blue-10`, `blue-20`, `blue`, `blue-40`, `blue-50`

**Reds:** `red-10`, `red-20`, `red`, `red-40`, `red-50`

**Yellows:** `yellow-10`, `yellow-20`, `yellow`, `yellow-30`, `yellow-40`, `yellow-50`

**Greens:** `green-10`, `green-20`, `green`, `green-40`, `green-50`

**Grays:** `white`, `gray-05`, `gray-10`, `gray-20`, `gray-30`, `gray-40`, `gray-50`, `gray-60`, `gray-70`, `gray-80`, `gray-90`, `gray`

**Purples:** `purple-10`, `purple`

**Special:** `transparent`

### Interactive Icons

```tsx
// With click handler
<IconSearch
  onClick={() => console.log('Search clicked')}
  className="cursor-pointer"
/>

// With hover effects
<IconSearch className="hover:text-blue-500 transition-colors" />

// As a button
<button>
  <IconSearch size={20} />
  Search
</button>
```

### Using Refs

```tsx
import { useRef } from 'react';
import { IconSearch } from '@freightos/icons';

function Component() {
  const iconRef = useRef<SVGSVGElement>(null);

  return <IconSearch ref={iconRef} />;
}
```

## TypeScript Support

### Using the Icon Type

The `Icon` type allows you to create type-safe variables that hold icon components:

```typescript
import { Icon, IconSearch, IconUser, IconDashboard } from '@freightos/icons';

// Define an interface with an icon property
interface NavItem {
  title: string;
  icon: Icon;  // Type for icon components
  path: string;
}

// Assign icon components (not JSX elements)
const navItems: NavItem[] = [
  { title: 'Search', icon: IconSearch, path: '/search' },
  { title: 'Profile', icon: IconUser, path: '/profile' },
  { title: 'Dashboard', icon: IconDashboard, path: '/dashboard' },
];

// Use in your component
function Navigation() {
  return (
    <nav>
      {navItems.map(item => {
        const IconComponent = item.icon;
        return (
          <a key={item.title} href={item.path}>
            <IconComponent size={20} />
            <span>{item.title}</span>
          </a>
        );
      })}
    </nav>
  );
}
```

### Dynamic Icon Selection

```typescript
import { Icon, IconSearch, IconUser, IconDashboard } from '@freightos/icons';

const iconMap: Record<string, Icon> = {
  search: IconSearch,
  user: IconUser,
  dashboard: IconDashboard,
};

function DynamicIcon({ name }: { name: string }) {
  const IconComponent = iconMap[name];

  if (!IconComponent) {
    console.warn(`Icon "${name}" not found`);
    return null;
  }

  return <IconComponent size={24} />;
}
```

## Available Icons

All 217 icons are available, organized by category:

- **Navigation**: Search, MenuOpen, MenuClose, ArrowBack, ArrowForward, CaretUp, CaretDown, etc.
- **Actions**: Edit, Trash, Save, Copy, Check, Close, Plus, Minus, Refresh, etc.
- **Transport**: ModeAir, ModeShip, ModeTruck, ModeTrain, ModeAirExpress, etc.
- **Business**: Company, Factory, Warehouse, Office, Billing, Pay, MoneyCase, etc.
- **Communication**: Message, Call, Envelope, ChatProgress, NotificationBell, etc.
- **User**: User, UserCircled, People, AddPerson, etc.
- **Status**: AlertCircled, InfoCircled, CheckCircled, Verified, Pending, etc.
- **Documents**: Document, Documents, Download, Upload, Archive, Attachment, etc.
- **Interface**: Dashboard, Settings, Filter, List, Grid, Table, Tile, etc.
- **Logistics**: Container, Box, Pallet, Crate, Customs, Insurance, Port, etc.

See your IDE's autocomplete for the complete list of all 217 icons.

## Icon Naming Convention

Icons follow a consistent naming pattern:

- SVG filename: `search.svg` → Component: `IconSearch`
- SVG filename: `menu-open.svg` → Component: `IconMenuOpen`
- SVG filename: `mode-air-express.svg` → Component: `IconModeAirExpress`

## Development

### Adding New Icons

1. Add your SVG file to `packages/icons/svg/` (use kebab-case naming: `my-icon.svg`)
2. Generate React components:

```bash
pnpm --filter @freightos/icons run generate
```

This will:
- Generate React components in `src/icons/`
- Update the index file with exports
- Replace hardcoded colors with `currentColor`

3. Build the package:

```bash
pnpm --filter @freightos/icons run build
```

### Available Scripts

```bash
# Generate icons from SVG files
pnpm --filter @freightos/icons run generate

# Build all formats (ESM + CJS + Types)
pnpm --filter @freightos/icons run build

# Generate and build in one command
pnpm --filter @freightos/icons run dev

# Clean build output
pnpm --filter @freightos/icons run clean
```

### Publishing

The package is published to npm as `@freightos/icons`:

```bash
pnpm --filter @freightos/icons run release:patch   # 1.0.12 → 1.0.13
pnpm --filter @freightos/icons run release:minor   # 1.0.12 → 1.1.0
pnpm --filter @freightos/icons run release:major   # 1.0.12 → 2.0.0
```

## Maintainer

Maintained by **Jiries Nasrawi** (jiries@freightos.com)

## License

MIT © Freightos