Basic Usage

There are two primary ways to use Font Awesome icons in your Phaser games:

Using icons as text with Phaser’s built-in text objects
Using the IconText component (recommended for most use cases)

Method 1: Using Icons as Text

This method gives you the most flexibility and control, as you’re working directly with Phaser’s text system.

Getting the Icon Character

First, use the getIconChar() function to get the Unicode character for an icon:

import { getIconChar } from 'font-awesome-for-phaser';

class MyScene extends Phaser.Scene {
  create() {
    // Get the character for the heart icon
    const heartChar = getIconChar('heart');

    // Create a Phaser text object with the icon
    const iconText = this.add.text(100, 100, heartChar, {
      font: "36px 'FontAwesome'", // ⚠️ Note: quotes around FontAwesome are required!
      color: '#ff0000',
    });

    iconText.setOrigin(0.5);
  }
}

Important: Font Name Format

The font name MUST be wrapped in single quotes inside the template string:

// ✅ Correct
font: "36px 'FontAwesome'"
font: "36px 'Font Awesome 6 Free'"

// ❌ Wrong - won't work!
font: '36px FontAwesome'
font: "36px FontAwesome"

Different Icon Styles

Font Awesome has different font families for different icon styles:

// Solid icons (most common)
const solidIcon = this.add.text(100, 100, getIconChar('heart'), {
  font: "36px 'FontAwesome'",
  color: '#ff0000',
});

// Regular icons
const regularIcon = this.add.text(200, 100, getIconChar('heart'), {
  font: "36px 'Font Awesome 6 Free'",
  color: '#0066cc',
});

// Brand icons (like social media logos)
const brandIcon = this.add.text(300, 100, getIconChar('github'), {
  font: "36px 'Font Awesome 6 Brands'",
  color: '#333333',
});

Method 2: Using IconText Component (Recommended)

The IconText component simplifies icon creation and handles font selection automatically:

import { IconText } from 'font-awesome-for-phaser';

class MyScene extends Phaser.Scene {
  create() {
    // Create a solid icon (default)
    const gamepadIcon = new IconText(this, 100, 100, 'gamepad', 64, {
      color: '#0066cc',
      iconStyle: 'solid',
    });
    this.add.existing(gamepadIcon);

    // Create a brand icon
    const githubIcon = new IconText(this, 200, 100, 'github', 48, {
      color: '#333333',
      iconStyle: 'brands',
    });
    this.add.existing(githubIcon);
  }
}

IconText Parameters

new IconText(
  scene: Phaser.Scene,     // The scene the icon belongs to
  x: number,               // X position
  y: number,               // Y position
  iconName: string,        // Font Awesome icon name (e.g., 'heart', 'star')
  size: number,            // Icon size in pixels
  options?: {
    color?: string,        // Hex color (e.g., '#ff0000')
    iconStyle?: 'solid' | 'regular' | 'brands', // Icon style
  }
)

Common Use Cases

Creating UI Icons

// Health heart icon
const healthIcon = new IconText(this, 20, 20, 'heart', 32, {
  color: '#ff0000',
});
this.add.existing(healthIcon);

// Coin/money icon
const coinIcon = new IconText(this, 100, 20, 'coins', 32, {
  color: '#ffd700',
});
this.add.existing(coinIcon);

// Settings gear
const settingsIcon = new IconText(this, 750, 20, 'gear', 32, {
  color: '#888888',
});
this.add.existing(settingsIcon);

Creating Interactive Icons (Buttons)

const playButton = new IconText(this, 400, 300, 'play', 64, {
  color: '#00ff00',
});

playButton.setInteractive({ useHandCursor: true });
playButton.on('pointerdown', () => {
  // Start game
  this.scene.start('GameScene');
});

this.add.existing(playButton);

Animating Icons

Since IconText extends Phaser.GameObjects.Text, you can use all Phaser’s animation features:

const starIcon = new IconText(this, 400, 300, 'star', 64, {
  color: '#ffff00',
});
this.add.existing(starIcon);

// Pulse animation
this.tweens.add({
  targets: starIcon,
  scale: 1.2,
  duration: 500,
  yoyo: true,
  repeat: -1,
});

Best Practices

Use IconText for simplicity - It handles font selection and provides cleaner code
Use direct text method for complex styling - When you need advanced text features
Cache icon characters - If using the same icon multiple times, store the character
Set origin for centering - Use setOrigin(0.5) to center icons properly
Consider icon style - Not all icons are available in all styles (solid/regular/brands)

Next Steps

Learn more about the IconText Component
Check available Icon Styles
Browse the API Reference