PHPackages                             marshmallow/nova-fontawesome - 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. marshmallow/nova-fontawesome

ActiveLibrary[Utility & Helpers](/categories/utility)

marshmallow/nova-fontawesome
============================

A Font Awesome 6/7 Field for Laravel Nova 5

v3.1.0(2mo ago)730.8k↑16.7%21MITPHPPHP ^8.2CI passing

Since Oct 4Pushed 2mo ago1 watchersCompare

[ Source](https://github.com/marshmallow-packages/nova-fontawesome)[ Packagist](https://packagist.org/packages/marshmallow/nova-fontawesome)[ RSS](/packages/marshmallow-nova-fontawesome/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (5)Dependencies (18)Versions (22)Used By (1)

[![Latest Version on Packagist](https://camo.githubusercontent.com/393f8b884f6ebd2ced5b44c7541e6dd755d28e23c2d6e973e9e4f30f9f65a41e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6d617273686d616c6c6f772f6e6f76612d666f6e74617765736f6d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/marshmallow/nova-fontawesome)[![Total Downloads](https://camo.githubusercontent.com/54fa464e38e7dacb72feddb716785894f1dd9ea90b78b0c8e231600ebc9c1eae/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6d617273686d616c6c6f772f6e6f76612d666f6e74617765736f6d652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/marshmallow/nova-fontawesome)[![CI](https://github.com/marshmallow-packages/nova-fontawesome/actions/workflows/ci.yml/badge.svg)](https://github.com/marshmallow-packages/nova-fontawesome/actions/workflows/ci.yml)

Laravel Nova Font Awesome Icons
===============================

[](#laravel-nova-font-awesome-icons)

A Laravel Nova field for selecting Font Awesome icons using the Font Awesome GraphQL API. This package loads icons **on-demand** via API calls, meaning you don't need to bundle all 30,000+ icons in your package.

Features
--------

[](#features)

- 🔍 **Smart search** - Uses Font Awesome's Algolia-powered fuzzy search
- 🚀 **On-demand loading** - Icons are fetched via API, not bundled
- 📜 **Infinite scroll** - Load more icons automatically as you scroll
- 🎨 **Style filtering** - Filter by solid, regular, brands, light, thin, duotone
- 👨‍👩‍👧‍👦 **Family support** - Classic, Brands, Duotone, Sharp, Sharp-Duotone
- 💾 **Caching** - API results are cached to reduce requests
- 🌙 **Dark mode** - Full support for Nova's dark mode
- ⚡ **Debounced search** - Prevents excessive API calls
- 📱 **Responsive** - Works great on all screen sizes
- 🔄 **Fallback icons** - Graceful degradation when API is unavailable
- 🔎 **Local fuzzy search** - Instant results for common icons
- 🔧 **CSS Strategies** - Self-hosted, Kit, or CDN CSS loading
- 🔀 **Legacy format support** - Auto-converts FA5 classes to modern format
- 🐛 **Debug endpoint** - Built-in troubleshooting tools

Important

This package was originally forked from [mdixon18/fontawesome](https://github.com/mdixon18/fontawesome). Since we were making many opinionated changes, we decided to continue development in our own version rather than submitting pull requests that might not benefit all users of the original package. You're welcome to use this package, we're actively maintaining it. If you encounter any issues, please don't hesitate to reach out.

Requirements
------------

[](#requirements)

- PHP ^8.2
- Laravel Nova ^5.0
- Laravel 11.x or 12.x
- Font Awesome 6.x or 7.x

> **Note:** For Nova 4 support, use version 1.x: `composer require marshmallow/nova-fontawesome:^1.0`

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require marshmallow/nova-fontawesome
```

### Step 2: Set up Font Awesome CSS

[](#step-2-set-up-font-awesome-css)

The package needs Font Awesome CSS to render icons. Choose one of these options:

**Option A: Self-hosted (Recommended for Pro users)**

1. Download Font Awesome from [fontawesome.com](https://fontawesome.com/download)
2. Extract and copy the `css` and `webfonts` folders to `public/vendor/fontawesome/`
3. Add to your `.env`: ```
    FONTAWESOME_CSS_STRATEGY=self-hosted
    FONTAWESOME_CSS_PATH=/vendor/fontawesome/css/all.min.css
    ```

**Option B: Font Awesome Kit (Easiest for Pro)**

1. Get your Kit ID from [fontawesome.com/kits](https://fontawesome.com/kits)
2. Add to your `.env`: ```
    FONTAWESOME_CSS_STRATEGY=kit
    FONTAWESOME_KIT_ID=abc123def
    ```

**Option C: CDN (Free icons only)**

No setup needed - this is the fallback if no other strategy is configured:

```
FONTAWESOME_CSS_STRATEGY=cdn
FONTAWESOME_CDN_VERSION=6.5.1
```

### Step 3: Publish config (optional)

[](#step-3-publish-config-optional)

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

### Step 4: Clear cache

[](#step-4-clear-cache)

```
php artisan cache:clear
```

That's it! The package uses the Font Awesome GraphQL API, so you don't need to manually download icon data.

CSS Loading Strategy
--------------------

[](#css-loading-strategy)

The package supports three CSS loading strategies (in order of priority):

### 1. Self-Hosted CSS (Recommended for Pro)

[](#1-self-hosted-css-recommended-for-pro)

Download Font Awesome CSS files and host them on your server:

1. Download Font Awesome from [fontawesome.com](https://fontawesome.com/download)
2. Extract and copy to `public/vendor/fontawesome/`
3. Set strategy in `.env`:

```
FONTAWESOME_CSS_STRATEGY=self-hosted
FONTAWESOME_CSS_PATH=/vendor/fontawesome/css/all.min.css
```

**Directory structure:**

```
public/
└── vendor/
    └── fontawesome/
        ├── css/
        │   └── all.min.css
        └── webfonts/
            └── (font files)

```

### 2. Font Awesome Kit

[](#2-font-awesome-kit)

Use your Font Awesome Kit for automatic Pro CSS loading:

```
FONTAWESOME_CSS_STRATEGY=kit
FONTAWESOME_KIT_ID=abc123def
```

Get your Kit ID from [fontawesome.com/kits](https://fontawesome.com/kits)

### 3. CDN (Fallback - Free only)

[](#3-cdn-fallback---free-only)

Load free icons from CDN (default fallback):

```
FONTAWESOME_CSS_STRATEGY=cdn
FONTAWESOME_CDN_VERSION=6.5.1
```

Usage
-----

[](#usage)

### Basic Usage

[](#basic-usage)

```
use Marshmallow\NovaFontAwesome\NovaFontAwesome;

public function fields(NovaRequest $request): array
{
    return [
        ID::make()->sortable(),

        NovaFontAwesome::make('Icon'),
    ];
}
```

### Available Methods

[](#available-methods)

#### Set Font Awesome Version

[](#set-font-awesome-version)

```
NovaFontAwesome::make('Icon')
    ->version('6.x') // or '7.x', or specific like '6.5.1'
```

#### Limit Icon Styles

[](#limit-icon-styles)

```
NovaFontAwesome::make('Icon')
    ->styles(['solid', 'brands']) // Only show solid and brand icons
```

Available styles: `solid`, `regular`, `light`, `thin`, `duotone`, `brands`

#### Set Icon Families

[](#set-icon-families)

```
NovaFontAwesome::make('Icon')
    ->families(['classic', 'brands', 'duotone', 'sharp'])
```

Available families: `classic`, `brands`, `duotone`, `sharp`, `sharp-duotone`

> **Note:** Duotone, Sharp, and Sharp-Duotone require Font Awesome Pro.

#### Free vs Pro Icons

[](#free-vs-pro-icons)

```
// Only free icons (default)
NovaFontAwesome::make('Icon')
    ->freeOnly()

// Include Pro icons (requires FA Pro subscription and API token)
NovaFontAwesome::make('Icon')
    ->includePro()
```

#### Font Awesome Kit ID (Pro)

[](#font-awesome-kit-id-pro)

Load Pro CSS using your Font Awesome Kit:

```
NovaFontAwesome::make('Icon')
    ->kitId('abc123def')
```

Or use a custom Pro CSS URL:

```
NovaFontAwesome::make('Icon')
    ->proCssUrl('https://pro.fontawesome.com/releases/v6.5.0/css/all.css')
```

#### Allow Empty/Null Values

[](#allow-emptynull-values)

```
NovaFontAwesome::make('Icon')
    ->nullable()
```

#### Custom Button Text

[](#custom-button-text)

```
NovaFontAwesome::make('Icon')
    ->addButtonText('Click Me!')
```

#### Limit Search Results (Per Page)

[](#limit-search-results-per-page)

```
NovaFontAwesome::make('Icon')
    ->maxResults(100) // Icons per page for infinite scroll
```

#### Minimum Search Length

[](#minimum-search-length)

```
NovaFontAwesome::make('Icon')
    ->minSearchLength(3) // Require 3 characters before searching
```

#### Set Default Icon

[](#set-default-icon)

```
NovaFontAwesome::make('Icon')
    ->defaultIcon('far', 'check-circle')
```

#### Persist Default Icon

[](#persist-default-icon)

If you want to persist the default icon (when they press clear it brings back the default so it can't be empty):

```
NovaFontAwesome::make('Icon')
    ->defaultIcon('far', 'check-circle')
    ->persistDefaultIcon()
```

#### Limit Available Icons

[](#limit-available-icons)

```
NovaFontAwesome::make('Icon')
    ->only([
        'facebook',
        'twitch',
        'twitter',
    ])
```

#### Client-Side Fuzzy Search

[](#client-side-fuzzy-search)

Enable or disable the local fuzzy search fallback:

```
NovaFontAwesome::make('Icon')
    ->fuzzySearch(true) // enabled by default
    ->fuzzySearchThreshold(0.3) // 0-1, lower = stricter matching
```

### Complete Example

[](#complete-example)

```
use Marshmallow\NovaFontAwesome\NovaFontAwesome;

public function fields(NovaRequest $request): array
{
    return [
        ID::make()->sortable(),

        Text::make('Name'),

        NovaFontAwesome::make('Icon')
            ->version('6.x')
            ->styles(['solid', 'regular', 'brands'])
            ->families(['classic', 'brands'])
            ->freeOnly()
            ->nullable()
            ->addButtonText('Choose an icon...')
            ->maxResults(100)
            ->minSearchLength(2)
            ->fuzzySearch(true)
            ->help('Select an icon to represent this item'),
    ];
}
```

Icon Class Format
-----------------

[](#icon-class-format)

### Stored Value Format

[](#stored-value-format)

The field stores icons in modern FA6/FA7 format:

```
"fa-solid fa-user"
"fa-regular fa-arrow-right"
"fa-brands fa-github"
"fa-duotone fa-solid fa-house"
"fa-sharp fa-solid fa-home"

```

### Legacy Format Support

[](#legacy-format-support)

The package automatically supports legacy FA5 shorthand classes for backwards compatibility:

Legacy FormatConverts To`fas fa-home``fa-solid fa-home``far fa-user``fa-regular fa-user``fab fa-github``fa-brands fa-github``fal fa-star``fa-light fa-star``fat fa-circle``fa-thin fa-circle``fad fa-house``fa-duotone fa-solid fa-house`When `convert_legacy_format` is enabled in config (default), legacy formats are automatically converted when saving.

How It Works
------------

[](#how-it-works)

This package uses the [Font Awesome GraphQL API](https://docs.fontawesome.com/apis/graphql) to:

1. **Search icons** - When you type in the search box, a GraphQL query is sent to Font Awesome's API
2. **Infinite scroll** - Results are paginated, loading more as you scroll down
3. **Cache results** - Search results are cached for 1 hour to reduce API calls
4. **Fallback gracefully** - If the API is unavailable, local fallback icons are used

### API Endpoints

[](#api-endpoints)

The package registers these API routes:

- `GET /nova-vendor/nova-fontawesome/search` - Search icons (with pagination)
- `GET /nova-vendor/nova-fontawesome/icon/{name}` - Get a specific icon
- `GET /nova-vendor/nova-fontawesome/metadata` - Get available families and styles
- `GET /nova-vendor/nova-fontawesome/config` - Get CSS configuration
- `GET /nova-vendor/nova-fontawesome/convert` - Convert legacy class format
- `GET /nova-vendor/nova-fontawesome/debug` - Troubleshooting endpoint
- `GET /nova-vendor/nova-fontawesome/fallback` - Get fallback icons

Configuration
-------------

[](#configuration)

After publishing the config file, you can modify `config/nova-fontawesome.php`:

```
return [
    // Default Font Awesome version (6.x or 7.x)
    'version' => env('FONTAWESOME_VERSION', '6.x'),

    // Cache duration in seconds (default: 1 hour)
    'cache_duration' => env('FONTAWESOME_CACHE_DURATION', 3600),

    // Only show free icons by default
    'free_only' => env('FONTAWESOME_FREE_ONLY', true),

    // Default styles to show
    'styles' => ['solid', 'regular', 'light', 'thin', 'duotone', 'brands'],

    // Available icon families
    'families' => ['classic', 'sharp', 'duotone', 'sharp-duotone', 'brands'],

    // Maximum search results per page
    'max_results' => env('FONTAWESOME_MAX_RESULTS', 100),

    // Optional API token for authenticated requests (required for Pro icons)
    'api_token' => env('FONTAWESOME_API_TOKEN'),

    // CSS loading strategy
    'css' => [
        'strategy' => env('FONTAWESOME_CSS_STRATEGY', 'self-hosted'),
        'path' => env('FONTAWESOME_CSS_PATH', '/vendor/fontawesome/css/all.min.css'),
        'kit_id' => env('FONTAWESOME_KIT_ID'),
        'cdn_version' => env('FONTAWESOME_CDN_VERSION', '6.5.1'),
    ],

    // Client-side fuzzy search settings
    'fuzzy_search' => [
        'enabled' => true,
        'threshold' => 0.3,
    ],

    // Auto-convert legacy FA5 classes to modern format
    'convert_legacy_format' => true,
];
```

### Environment Variables

[](#environment-variables)

Add these to your `.env` file to customize the configuration:

```
FONTAWESOME_VERSION=6.x
FONTAWESOME_CACHE_DURATION=3600
FONTAWESOME_FREE_ONLY=true
FONTAWESOME_MAX_RESULTS=100

# CSS Strategy (self-hosted, kit, or cdn)
FONTAWESOME_CSS_STRATEGY=self-hosted
FONTAWESOME_CSS_PATH=/vendor/fontawesome/css/all.min.css

# Only needed for Pro icons
FONTAWESOME_API_TOKEN=your-api-token-here

# Pro CSS loading options (pick one)
FONTAWESOME_KIT_ID=abc123def
```

### Getting a Font Awesome API Token

[](#getting-a-font-awesome-api-token)

To access Font Awesome Pro icons or improve API rate limits, you'll need an API token:

1. **Create or log in to your Font Awesome account** at [fontawesome.com/account](https://fontawesome.com/account)
2. **Navigate to API Tokens** section at [fontawesome.com/account#api-tokens](https://fontawesome.com/account#api-tokens)
3. **Generate a new token** by clicking "Create Token"
4. **Copy the token** and add it to your `.env` file: ```
    FONTAWESOME_API_TOKEN=your-token-here
    ```

> **Note:** API tokens are automatically exchanged for short-lived access tokens and cached for performance. The package handles token refresh automatically.

Displaying Icons
----------------

[](#displaying-icons)

### In Blade Views

[](#in-blade-views)

```

```

### With Tailwind/Vite

[](#with-tailwindvite)

If rendering icons in your frontend (outside Nova), make sure Font Awesome CSS is loaded:

```

```

Or via your `vite.config.js`:

```
// Import in your JS
import '/public/vendor/fontawesome/css/all.min.css';
```

### Helper Method (Optional)

[](#helper-method-optional)

You can add a helper to your model:

```
public function getIconHtmlAttribute(): string
{
    if (!$this->icon) {
        return '';
    }

    return sprintf('', e($this->icon));
}
```

Troubleshooting
---------------

[](#troubleshooting)

### Debug Endpoint

[](#debug-endpoint)

Visit `/nova-vendor/nova-fontawesome/debug` to check:

- API connectivity
- Token exchange status
- Search functionality
- Cache status
- CSS configuration

### Icons not loading

[](#icons-not-loading)

1. Check the debug endpoint for API errors
2. Check that your server can reach `api.fontawesome.com`
3. Check Laravel logs for errors
4. Clear the cache: `php artisan cache:clear`

### CSS not loading / Icons showing as boxes

[](#css-not-loading--icons-showing-as-boxes)

1. Check your CSS strategy in config
2. For self-hosted: verify files exist in `public/vendor/fontawesome/`
3. For Kit: verify your Kit ID is correct
4. Check browser console for 404 errors

### Styles not filtering correctly

[](#styles-not-filtering-correctly)

Make sure you're using valid style names: `solid`, `regular`, `light`, `thin`, `duotone`, `brands`

### Pro icons not showing

[](#pro-icons-not-showing)

1. Verify you have an active Font Awesome Pro subscription
2. Check that your API token is correctly set in `.env`
3. Use the debug endpoint to verify token exchange
4. Ensure your CSS strategy supports Pro icons (self-hosted or kit)

Upgrading
---------

[](#upgrading)

### From v1.x to v2.x

[](#from-v1x-to-v2x)

1. Update `composer.json` requirements
2. Update `package.json` - Vite replaces Laravel Mix
3. Rebuild assets: `npm install && npm run build`
4. Update config file if published (new `css` section replaces `pro_css`)
5. See [UPGRADE.md](UPGRADE.md) for detailed migration guide

Development
-----------

[](#development)

### Building Assets

[](#building-assets)

```
npm install
npm run dev      # Development build
npm run build    # Production build
npm run watch    # Watch mode
```

### Running Tests

[](#running-tests)

```
composer test
```

### Code Style

[](#code-style)

```
composer lint        # Fix code style
composer lint-check  # Check without fixing
```

### Static Analysis

[](#static-analysis)

```
composer analyse
```

Licence
-------

[](#licence)

The MIT License (MIT). Please see [License File](LICENCE) for more information.

Sponsorships
------------

[](#sponsorships)

If you are reliant on this package in your production applications, consider [sponsoring us](https://github.com/sponsors/marshmallow-packages)! It is the best way to help us keep doing what we love to do: making great open source software.

Contributing
------------

[](#contributing)

Feel free to suggest changes, ask for new features or fix bugs yourself. We're sure there are still a lot of improvements that could be made, and we would be very happy to merge useful pull requests.

### Special thanks to

[](#special-thanks-to)

- [All Contributors](../../contributors)
- [mdixon18](https://github.com/mdixon18/fontawesome)
- [duckzland](https://github.com/duckzland/fontawesome)

Made with love for open source
------------------------------

[](#made-with-love-for-open-source)

At [Marshmallow](https://marshmallow.nl) we use a lot of open source software as part of our daily work. So when we have an opportunity to give something back, we're super excited!

We hope you will enjoy this small contribution from us and would love to [hear from you](mailto:hello@marshmallow.nl) if you find it useful in your projects. Follow us on [Twitter](https://x.com/marshmallow_dev) for more updates!

###  Health Score

60

—

FairBetter than 99% of packages

Maintenance88

Actively maintained with recent releases

Popularity35

Limited adoption so far

Community16

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor1

Top contributor holds 89.2% of commits — single point of failure

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

Every ~143 days

Recently: every ~14 days

Total

20

Last Release

62d ago

Major Versions

v0.2.1 → v1.0.02021-12-22

v1.0.1 → v2.0.02022-05-04

v2.1.0 → v3.0.02026-01-19

PHP version history (4 changes)v0.1.0PHP >=7.1.0

v1.0.0PHP ^7.4|^8.0|^8.1

v2.0.0PHP ^8.0|^8.1

v3.0.0PHP ^8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/be33d2624e24c516e73892b0929447cc762f3622c024ab8d0d2a59042e5d2c7f?d=identicon)[marshmallow](/maintainers/marshmallow)

---

Top Contributors

[![LTKort](https://avatars.githubusercontent.com/u/2412670?v=4)](https://github.com/LTKort "LTKort (116 commits)")[![stefvanesch](https://avatars.githubusercontent.com/u/46725619?v=4)](https://github.com/stefvanesch "stefvanesch (6 commits)")[![duckzland](https://avatars.githubusercontent.com/u/1064954?v=4)](https://github.com/duckzland "duckzland (4 commits)")[![mdixon18](https://avatars.githubusercontent.com/u/7197697?v=4)](https://github.com/mdixon18 "mdixon18 (4 commits)")

---

Tags

laravelFontAwesomenovanova-5fontawesome 6fontawesome 7

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/marshmallow-nova-fontawesome/health.svg)

```
[![Health](https://phpackages.com/badges/marshmallow-nova-fontawesome/health.svg)](https://phpackages.com/packages/marshmallow-nova-fontawesome)
```

###  Alternatives

[datomatic/nova-enum-field

A Laravel Nova PHP 8.1 enum field with filters

20134.2k](/packages/datomatic-nova-enum-field)[norman-huth/nova-assets-changer

Change Nova resources

2570.1k](/packages/norman-huth-nova-assets-changer)[advoor/nova-editor-js

A Laravel Nova field bringing EditorJs magic to Nova.

92179.0k3](/packages/advoor-nova-editor-js)[simplesquid/nova-enum-field

A Laravel Nova field to add enums to resources.

52391.9k2](/packages/simplesquid-nova-enum-field)[sbine/route-viewer

A Laravel Nova tool to view your registered routes.

57215.9k](/packages/sbine-route-viewer)[swooinc/nova-countdown

A countdown card for Laravel Nova.

1224.5k](/packages/swooinc-nova-countdown)

PHPackages © 2026

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