@freightos/icons

中文文档
3.0.1发布于 2026/04/05MITTypeScriptESM + CJS零依赖近 30 天下载 1976

A comprehensive icon library for Freightos applications with full TypeScript support

原始使用文档
文档目录20 节
  1. Features
  2. Installation
  3. Usage Guide
  4. Basic Usage
  5. Props
  6. Sizing
  7. Coloring
  8. Interactive Icons
  9. Using Refs
  10. TypeScript Support
  11. Using the Icon Type
  12. Dynamic Icon Selection
  13. Available Icons
  14. Icon Naming Convention
  15. Development
  16. Adding New Icons
  17. Available Scripts
  18. Publishing
  19. Maintainer
  20. License

@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 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

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:

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:

PropTypeDefaultDescription
sizeIconSize | number | string'1em'Width and height — semantic tokens (xs, sm, md, lg), pixel numbers, or CSS strings
colorFreightosColor | string'currentColor'Color of the icon - supports design system colors with autocomplete or any CSS color value
classNamestring-Additional CSS classes
...propsSVGProps<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:

// 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:

// 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

// 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

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:

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

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:
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
  1. Build the package:
pnpm --filter @freightos/icons run build

Available Scripts

# 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:

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 ([email protected])

License

MIT © Freightos

版本与发布记录

@freightos/icons 共发布 20 个版本,首次发布于 2025/11/02;过去 12 个月发布了 13 个版本。

版本发布日期距今
3.0.1latest2026/04/057 个月前
3.0.02026/04/027 个月前
1.0.172026/03/168 个月前
1.0.162026/03/168 个月前
1.0.152026/03/108 个月前
1.0.122026/01/0910 个月前

关于 @freightos/icons 的常见问题

@freightos/icons 是什么?

A comprehensive icon library for Freightos applications with full TypeScript support

如何安装 @freightos/icons?

在项目目录运行 npm install @freightos/icons,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:react(>=16.8.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@freightos/icons 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@freightos/icons 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@freightos/icons 可以商用吗?

@freightos/icons 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@freightos/icons 的下载量有多少?

根据 npm 官方下载统计,@freightos/icons 在 2026/10/16 – 2026/11/14 这 30 天内被下载 1,976 次,日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@freightos/icons 还在维护吗?

最新版本 3.0.1 发布于 2026/04/05(7 个月前);至今共发布 20 个版本,其中过去 12 个月发布了 13 个;首次发布于 2025/11/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。