PHPackages                             visual1/statamic-font-awesome-fieldtype - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. visual1/statamic-font-awesome-fieldtype

ActiveStatamic-addon[Utility & Helpers](/categories/utility)

visual1/statamic-font-awesome-fieldtype
=======================================

Font Awesome fieldtype for Statamic with color and size controls, supporting both Free and Pro versions

1.0.0(7mo ago)011proprietaryJavaScriptPHP ^8.1

Since Oct 3Pushed 7mo agoCompare

[ Source](https://github.com/visual1-development/statamic-font-awesome-fieldtype)[ Packagist](https://packagist.org/packages/visual1/statamic-font-awesome-fieldtype)[ RSS](/packages/visual1-statamic-font-awesome-fieldtype/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Font Awesome Fieldtype for Statamic
===================================

[](#font-awesome-fieldtype-for-statamic)

[![Statamic](https://camo.githubusercontent.com/b48365f237cbc5133ecfbcf94c7f92afe5230b3a080118c5b36c341903cf9145/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f53746174616d69632d342e30253242253230253743253230352e302532422d4646323639452e737667)](https://statamic.com)[![Font Awesome](https://camo.githubusercontent.com/35c58155c04a0d1cbb8174f67d8f532c2d77d41554decfde2c2ffb95bde49167/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f466f6e74253230417765736f6d652d362e782d3532384444372e737667)](https://fontawesome.com)

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

[](#-features)

### 🔍 **Smart Search & Performance**

[](#-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**

[](#-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**

[](#-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**

[](#-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
--------------

[](#-installation)

### Via Composer from GitHub

[](#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

[](#manual-installation)

1. Clone or download from [GitHub](https://github.com/Cedou90/visual1-font-awesome-fieldtype)
2. Extract to `packages/visual1/font-awesome-fieldtype/`
3. Add to your main `composer.json` autoload section:

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

4. Run `composer dump-autoload`

⚙️ Configuration
----------------

[](#️-configuration)

### Basic Setup

[](#basic-setup)

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

### Pro Setup (Optional)

[](#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](https://fontawesome.com/account)
- **Kit ID**: [Font Awesome Kits](https://fontawesome.com/kits)

### Publish Configuration (Optional)

[](#publish-configuration-optional)

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

This creates `config/fontawesome.php` for advanced customization.

🎯 Usage
-------

[](#-usage)

### 1. Add to Blueprint

[](#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

[](#2-fieldtype-configuration)

OptionTypeDefaultDescription`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

[](#3-add-font-awesome-to-your-layout)

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

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

**Complete example:**

```

    {{ title ?? site:name }}

    {{ partial src="font-awesome::partials/font-awesome" }} {{ vite
    src="resources/js/site.js|resources/css/site.scss" }}

    {{ template_content }}

```

### 4. Template Usage

[](#4-template-usage)

#### Recommended Icon Rendering

[](#recommended-icon-rendering)

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

```

{{ 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)

[](#simple-usage-use-with-caution)

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

```

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

[](#advanced-usage)

```

{{ if {font_awesome:exists field="my_icon"} }}

        {{ font_awesome:icon field="my_icon" class="primary-icon" }}

{{ /if }}

{{ my_icon }}

    Icon: {{ name }}
    Style: {{ style }}
{{ /my_icon }}
```

#### Direct HTML Usage

[](#direct-html-usage)

```

  {{ my_icon:name }}

```

📊 Available Icon Styles
-----------------------

[](#-available-icon-styles)

StyleClassAvailabilityDescription**Solid**`fas`Free & ProBold, filled icons**Regular**`far`Free & ProOutlined 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 & ProBrand and logo icons🔧 API Integration
-----------------

[](#-api-integration)

### Font Awesome Pro API

[](#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

[](#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
----------------------

[](#-performance-features)

### Search-Based Lazy Loading

[](#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

[](#caching-strategy)

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

### Performance Benefits

[](#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
---------------

[](#-customization)

### CSS 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)

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

[](#-troubleshooting)

### Common Issues

[](#common-issues)

#### Icons Not Loading

[](#icons-not-loading)

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

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

#### Pro Icons Showing as Unavailable

[](#pro-icons-showing-as-unavailable)

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

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

#### Icons Not Rendering on Frontend

[](#icons-not-rendering-on-frontend)

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

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

### Cache Issues

[](#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
------------------------

[](#-advanced-configuration)

### Custom Icon Sets

[](#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

[](#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
---------------

[](#-api-reference)

### Fieldtype Methods

[](#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

[](#antlers-tags)

```

{{ font_awesome:icon field="icon_field" }}

{{ font_awesome:class field="icon_field" }}

{{ font_awesome:exists field="icon_field" }}
```

### JavaScript Events

[](#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
--------------

[](#-contributing)

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

### Development Setup

[](#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

[](#testing)

```
composer test
npm run test
```

📄 License
---------

[](#-license)

This addon is proprietary software. See [LICENSE](LICENSE) for details.

🆘 Support
---------

[](#-support)

- **Issues**: [GitHub Issues](https://github.com/Cedou90/visual1-font-awesome-fieldtype/issues)
- **Email**:

🎉 Credits
---------

[](#-credits)

Created with ❤️ by [Visual1](https://visual1.com.au)

- **Font Awesome** - [fontawesome.com](https://fontawesome.com)
- **Statamic** - [statamic.com](https://statamic.com)
- **Vue.js** - [vuejs.org](https://vuejs.org)

---

**Made with ❤️ for the Statamic community**

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance63

Regular maintenance activity

Popularity5

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

228d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8f6a7e7da0dd88a904d66e34e5c94c56a130e2c2e0aff287c5d16b27ddc34346?d=identicon)[Baumi-Dev](/maintainers/Baumi-Dev)

---

Tags

iconscmsfont-awesomestatamicfieldtype

### Embed Badge

![Health badge](/badges/visual1-statamic-font-awesome-fieldtype/health.svg)

```
[![Health](https://phpackages.com/badges/visual1-statamic-font-awesome-fieldtype/health.svg)](https://phpackages.com/packages/visual1-statamic-font-awesome-fieldtype)
```

###  Alternatives

[marcorieser/statamic-livewire

A Laravel Livewire integration for Statamic.

2381.5k10](/packages/marcorieser-statamic-livewire)[withcandour/aardvark-seo

Save time and get your Statamic site to rank better with the SEO addon for Statamic.

13128.3k](/packages/withcandour-aardvark-seo)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)