README

A Font Awesome fieldtype for Statamic that provides a searchable icon interface with visual color and size controls. Supports both Font Awesome Free and Pro with automatic fallback.

✨ Features

🔍 Smart Search & Performance

Search-based lazy loading - Only loads icons when you search (3+ characters)
Instant popular icons - 25 most common icons load immediately (0ms)
Intelligent caching - Dual-layer caching system for optimal performance
Real-time filtering - Style-based filtering with live icon validation

🎨 Rich User Experience

Live icon preview - See icons as you search with customizable color picker
Multiple icon sizes - Preview icons in normal, large, extra-large, and huge sizes
Copy to clipboard - One-click copy for CSS classes, HTML, Antlers tags, and direct usage
Dark mode support - Beautiful interface that adapts to your CP theme
Responsive design - Works perfectly on desktop, tablet, and mobile

🔐 Pro & Free Support

Font Awesome Pro API - Full GraphQL integration with token authentication
Font Awesome Free - Complete free icon set via GitHub API
Kit CSS loading - Automatic Pro Kit CSS/JS loading for authenticated users
Style validation - Real-time checking of icon availability per style
Graceful fallbacks - Seamless fallback from Pro to Free when needed

⚡ Developer Experience

Zero configuration - Works out of the box with sensible defaults
Flexible configuration - Extensive fieldtype options for customization
Statamic integration - Full support for blueprints, fieldsets, and replicators
Antlers tags - Simple template tags for rendering icons
Data augmentation - Rich icon data available in templates

📦 Installation

Via Composer from GitHub

Add this repository to your composer.json:

{
  "repositories": [
    {
      "type": "vcs",
      "url": "https://github.com/Cedou90/visual1-font-awesome-fieldtype.git"
    }
  ],
  "require": {
    "visual1/statamic-font-awesome-fieldtype": "^1.0"
  }
}

Then run:

composer install

Manual Installation

Clone or download from GitHub
Extract to packages/visual1/font-awesome-fieldtype/
Add to your main composer.json autoload section:

{
  "autoload": {
    "psr-4": {
      "Visual1\\FontAwesome\\": "packages/visual1/font-awesome-fieldtype/src/"
    }
  }
}

Run composer dump-autoload

⚙️ Configuration

Basic Setup

The fieldtype works immediately after installation with Font Awesome Free. No configuration required!

Pro Setup (Optional)

For Font Awesome Pro features, add your credentials to .env:

# Font Awesome Pro API Token (required for Pro icons)
FONTAWESOME_API_TOKEN=your-pro-api-token-here

# Font Awesome Kit ID (optional, for Pro CSS loading)
FONTAWESOME_KIT_ID=your-kit-id-here

Get your credentials from:

API Token: Font Awesome Account
Kit ID: Font Awesome Kits

Publish Configuration (Optional)

php artisan vendor:publish --tag=fontawesome-config

This creates config/fontawesome.php for advanced customization.

🎯 Usage

1. Add to Blueprint

fields:
  my_icon:
    type: font_awesome
    display: Select Icon
    instructions: Choose a Font Awesome icon
    icon_styles:
      - solid
      - regular
      - brands
    show_preview: true
    hide_unavailable: true

2. Fieldtype Configuration

Option	Type	Default	Description
`icon_styles`	Array	`['solid']`	Icon styles to include (solid, regular, light, thin, duotone, brands)
`show_preview`	Boolean	`true`	Enable live icon preview in dropdown and preview area
`hide_unavailable`	Boolean	`true`	Hide icons not available in current Font Awesome setup
`placeholder`	String	`'Search Font Awesome icons...'`	Custom placeholder text for search field

3. Add Font Awesome to Your Layout

Add this line to your layout file (resources/views/layout.antlers.html) in the <head> section:

{{ partial src="font-awesome::partials/font-awesome" }}

Complete example:

<!doctype html>
<html lang="{{ site:short_locale }}">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{{ title ?? site:name }}</title>

    <!-- Font Awesome (Required) -->
    {{ partial src="font-awesome::partials/font-awesome" }} {{ vite
    src="resources/js/site.js|resources/css/site.scss" }}
  </head>
  <body>
    {{ template_content }}
  </body>
</html>

4. Template Usage

Recommended Icon Rendering

Use this recommended syntax that handles both simple icons and icons with color/size settings:

<!-- RECOMMENDED: Works with all data formats -->
<!-- Replace "my_icon" with your actual field name -->
{{ if my_icon.icon }}
    {{ font_awesome:icon icon="{my_icon.icon}" color="{my_icon.color}" size="{my_icon.size}" }}
{{ else }}
    {{ font_awesome:icon field="my_icon" }}
{{ /if }}

Important: Replace my_icon with your actual field name. For example, if your field is called header_icon, use:

{{ if header_icon.icon }}
    {{ font_awesome:icon icon="{header_icon.icon}" color="{header_icon.color}" size="{header_icon.size}" }}
{{ else }}
    {{ font_awesome:icon field="header_icon" }}
{{ /if }}

This conditional approach:

✅ Handles color/size data without errors
✅ Falls back gracefully for simple string values
✅ Prevents "Array to string conversion" errors
✅ Future-proof against data format changes

Note: The fieldtype preview will automatically show this syntax with your actual field name. Simply copy and paste it for error-free usage.

Simple Usage (Use with Caution)

For simple string-only icons (no color/size):

<!-- Only use if you're certain the field contains simple string data -->
{{ font_awesome:icon field="my_icon" }}

⚠️ Warning: This simple syntax will cause errors if the field contains color/size data. Always prefer the bulletproof conditional syntax above.

Advanced Usage

<!-- Check if icon exists -->
{{ if {font_awesome:exists field="my_icon"} }}
    <div class="icon-wrapper">
        {{ font_awesome:icon field="my_icon" class="primary-icon" }}
    </div>
{{ /if }}

<!-- Get just the CSS class -->
<span class="icon {{ font_awesome:class field="my_icon" }}"></span>

<!-- Access augmented data -->
{{ my_icon }}
    <i class="{{ class }}"></i>
    <span>Icon: {{ name }}</span>
    <span>Style: {{ style }}</span>
{{ /my_icon }}

Direct HTML Usage

<!-- Direct icon rendering -->
<i class="{{ my_icon }}"></i>

<!-- With augmented data -->
<div class="icon-info">
  <i class="{{ my_icon:class }}"></i>
  <span>{{ my_icon:name }}</span>
</div>

📊 Available Icon Styles

Style	Class	Availability	Description
Solid	`fas`	Free & Pro	Bold, filled icons
Regular	`far`	Free & Pro	Outlined icons
Light	`fal`	Pro Only	Lighter weight icons
Thin	`fat`	Pro Only	Thinnest weight icons
Duotone	`fad`	Pro Only	Two-color icons
Brands	`fab`	Free & Pro	Brand and logo icons

🔧 API Integration

Font Awesome Pro API

The addon uses the official Font Awesome Pro GraphQL API for authenticated users:

query {
  release(version: "6.x") {
    icons {
      id
      label
      styles
      unicode
    }
  }
}

Font Awesome Free API

For free users, icons are loaded from the GitHub metadata:

https://raw.githubusercontent.com/FortAwesome/Font-Awesome/6.x/metadata/icons.json

🚀 Performance Features

Search-Based Lazy Loading

Instead of loading 3,800+ icons upfront, the fieldtype uses intelligent lazy loading:

Popular icons load instantly (0ms)
Search results load only when needed (3+ characters)
API calls are cached for 30 minutes
Search queries are cached for 10 minutes

Caching Strategy

Popular Icons Cache - 25 most common icons always available
Full Icon Cache - Complete icon set cached for 30 minutes
Search Cache - Individual search queries cached for 10 minutes
Status Cache - Icon availability status cached for session
Style Support Cache - CSS style detection cached for session

Performance Benefits

90% faster initial load time
95% less memory usage until search
Zero API calls for popular icons
Minimal bandwidth usage with intelligent caching

🎨 Customization

CSS Customization

The fieldtype uses Tailwind CSS classes and provides CSS custom properties for theming:

.font-awesome-fieldtype {
  --fa-fieldtype-primary: #3b82f6;
  --fa-fieldtype-secondary: #6b7280;
  --fa-fieldtype-background: #ffffff;
  --fa-fieldtype-border: #d1d5db;
}

Dark Mode

Dark mode is automatically supported and follows your Control Panel theme:

@media (prefers-color-scheme: dark) {
  .font-awesome-fieldtype {
    --fa-fieldtype-background: #1f2937;
    --fa-fieldtype-border: #374151;
  }
}

🔍 Troubleshooting

Common Issues

Icons Not Loading

Problem: Icons don't appear in search results Solution:

Check your API token in .env
Verify network connectivity
Clear the addon cache with the refresh button

Pro Icons Showing as Unavailable

Problem: Pro icons show as "PRO" or unavailable Solutions:

Add FONTAWESOME_API_TOKEN to your .env file
Verify your Pro subscription is active
Check that your API token has correct permissions

Icons Not Rendering on Frontend

Problem: Icons show as squares or don't appear Solutions:

Ensure Font Awesome CSS is loaded on your frontend
For Pro users, add your Kit ID to .env
Verify CSS classes are correct in templates

Cache Issues

To clear all caches, use the refresh button in the fieldtype interface or manually clear:

# Clear Statamic cache
php artisan cache:clear

# Clear compiled views
php artisan view:clear

🔧 Advanced Configuration

Custom Icon Sets

While this addon focuses on Font Awesome, you can extend it for custom icon sets:

// In a service provider
$this->app['events']->listen('fontawesome.icons.loading', function ($query) {
    // Add custom icons to search results
    return array_merge($query->icons, $customIcons);
});

Performance Tuning

For high-traffic sites, consider these optimizations:

// config/fontawesome.php
return [
    'cache_duration' => 3600, // 1 hour instead of 30 minutes
    'search_cache_duration' => 1800, // 30 minutes instead of 10
    'max_search_results' => 50, // Reduce from 100 for faster loading
];

📚 API Reference

Fieldtype Methods

// Get augmented icon data
$iconData = $entry->augmentedValue('my_icon');

// Check if field has value
$hasIcon = $fieldtype->hasValue($value);

// Process field data
$processed = $fieldtype->process($data);

Antlers Tags

<!-- Render icon -->
{{ font_awesome:icon field="icon_field" }}

<!-- Get CSS class only -->
{{ font_awesome:class field="icon_field" }}

<!-- Check if icon exists -->
{{ font_awesome:exists field="icon_field" }}

JavaScript Events

// Listen for icon selection
document.addEventListener("fa-icon-selected", function (event) {
  console.log("Selected icon:", event.detail.icon);
});

// Listen for search completion
document.addEventListener("fa-search-complete", function (event) {
  console.log("Search results:", event.detail.results);
});

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

git clone https://github.com/Cedou90/visual1-font-awesome-fieldtype.git
cd statamic-font-awesome-fieldtype
composer install
npm install
npm run dev

Testing

composer test
npm run test

📄 License

This addon is proprietary software. See LICENSE for details.

🆘 Support

Issues: GitHub Issues
Email: support@visual1.com.au

🎉 Credits

Created with ❤️ by Visual1

Font Awesome - fontawesome.com
Statamic - statamic.com
Vue.js - vuejs.org

Made with ❤️ for the Statamic community

visual1 / statamic-font-awesome-fieldtype

Maintainers

Details