ui5-fontawesome-lib

🎨 UI5 FontAwesome Icons Library

Enhance your SAP UI5/OpenUI5 applications with modern Font Awesome icons! 🚀

This library seamlessly integrates Font Awesome icons into the SAP UI5 icon system, providing access to thousands of beautiful, scalable icons for your Fiori applications. Have a look at the ui5-icon-explorer project or directly visit ie.kernich.de for an example integration and interactive showcase of all free Font Awesome icons together with the built-in icons.

🎯 Features

• ✨ Seamless Integration: Use Font Awesome icons with standard UI5 Icon controls
• 🎨 3 Icon Styles: Regular, Solid, and Brand icons
• 🕰️ Backwards compatible: Works with UI5 1.71 and newer (uses sap/ui/core/Lib when available, falls back to Core#initLibrary on older releases)

📋 Icon Mapping

🛠️ Setup & Configuration

Add the fontawesome.icons.lib library dependency to your manifest.json and follow one of the next methods.

{
  "dependencies": {
    "minUI5Version": "1.71.0",
    "libs": {
      "sap.ui.core": {},
      "sap.m": {},
      "fontawesome.icons.lib": {}
    }
  }
}

If using TypeScript, add ui5-fontawesome-lib to types definition.

{
  "compilerOptions": {
    "types": [
      "@sapui5/ts-types-esm",
      "ui5-fontawesome-lib"
    ]
  }
}

Method 1: Using NPM Package (Recommended)

Install Dependencies

npm i ui5-fontawesome-lib

That should be it. The UI5 tooling will recognize the UI5 dependency (verifiable via UI5 CLI command UI5 tree) and take care of loading it for you.

with UI5 middleware (alternative recommendation)

npm i ui5-fontawesome-lib && npm i -D ui5-middleware-servestatic

Add the following configuration to your ui5.yaml:

server:
  customMiddleware:
    - name: ui5-middleware-servestatic
      afterMiddleware: compression
      mountPath: /resources/fontawesome/icons/lib/
      configuration:
        npmPackagePath: 'ui5-fontawesome-lib/dist/resources/fontawesome/icons/lib'

Method 2: Using CDN

Add https://cdn.kernich.de/ui5-fontawesome-lib/resources/fontawesome/icons/lib to your resource roots for fontawesome.icons.lib

<script
  id="sap-ui-bootstrap"
  src="https://sdk.openui5.org/resources/sap-ui-core.js"
  data-sap-ui-resource-roots='{
    "my.example.app": "./",
    "fontawesome.icons.lib": "https://cdn.kernich.de/ui5-fontawesome-lib/resources/fontawesome/icons/lib"
  }'
  data-sap-ui-on-init="module:sap/ui/core/ComponentSupport"
  data-sap-ui-compat-version="edge"
  data-sap-ui-frame-options="trusted"
  data-sap-ui-async="true"
></script>

Method 3: Local setup (for development)

Clone this repository and add it as a dependency to your local UI5 project setup.

💻 Usage Examples

Basic Icon Usage

<!-- Regular icons -->
<Icon src="sap-icon://fa-regular/heart" />

<!-- Solid icons -->
<Icon src="sap-icon://fa-solid/star" />

<!-- Brand icons -->
<Icon src="sap-icon://fa-brands/github" />

With Icon Properties

<Icon 
    src="sap-icon://fa-solid/rocket" 
    size="2rem" 
    color="#0070f3" 
    tooltip="Launch application" />

In JavaScript/TypeScript

import Icon from "sap/ui/core/Icon";

const icon = new Icon({
    src: "sap-icon://fa-solid/check-circle",
    size: "1.5rem",
    color: "green"
});

🎨 Font Awesome Pro Support

Want to use Font Awesome Pro icons? Here's how to extend this library:

Setup Font Awesome Pro Icons

1. Follow the official Font Awesome tutorial: Font Awesome Pro Setup

2. Create .npmrc file:

   @fortawesome:registry=https://npm.fontawesome.com/
   //npm.fontawesome.com/:_authToken=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
   

3. Install Pro package:

   npm install --save @fortawesome/fontawesome-pro

4. Update build process: Modify generate.js to include Pro font files by changing const loadPro = false; to const loadPro = true;

5. Register new styles: Update library.ts to register additional icon styles

🚀 Development

Quick Start

# Clone the repository
git clone https://github.com/ui5-community/ui5-fontawesome-lib.git
cd ui5-fontawesome-lib

# Install dependencies
npm install

# Start development server
npm start

Visit http://localhost:8080/ to see the icon browser with search functionality.

📸 Screenshot

Interactive icon browser with search functionality - run npm start to see it in action!

Available Scripts

Debugging

Enable sourcemaps in your browser's developer console to debug the original TypeScript code. Use Ctrl/Cmd + P in Chrome to open specific .ts files.

📊 Project Structure

ui5-fontawesome-lib/
├── src/                    # Source files
│   ├── fonts/             # Font Awesome font files
│   ├── library.ts         # Main library file
│   └── themes/            # UI5 themes
├── test/                  # Test files
├── dist/                  # Build output
└── scripts/               # Build and deployment scripts

🤝 Contributing

We welcome contributions! Please feel free to submit issues and pull requests.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the Apache Software License, version 2.0 - see the LICENSE file for details.

🔗 Links

• 📦 NPM Package
• 🐙 GitHub Repository
• 📚 Font Awesome Documentation
• 🎯 SAP UI5 Documentation

⭐ Support

If you find this library helpful, please consider giving it a star on GitHub! ⭐

Made with ❤️ for the SAP UI5 community