Documentation

Installation

Step 1: Upload the Plugin Files

Download the plugin ZIP file from your purchase confirmation email or account dashboard.
In your WordPress admin dashboard, navigate to Plugins > Add New.
Click on Upload Plugin at the top of the page.
Choose the downloaded ZIP file (acf-elementor-custom-icons.zip) and click Install Now.

Step 2: Activate the Plugin

After installation, click on Activate Plugin.
The plugin is now active and ready for configuration.

Upgrading from 1.x? Version 2.0 is fully backwards-compatible. Existing widgets and ACF fields keep working without any manual migration. The Settings menu was reorganized — see the License Activation section below for the new path.

License Activation

Activating your license key ensures you receive automatic updates and unlocks the icon picker and Elementor widgets.

Step 1: Navigate to the License Settings

In the WordPress admin dashboard, go to Settings > AECI Custom Icons.
The page opens on the License tab by default.

Step 2: Enter Your License Key

In the License Key field, paste the license key provided in your purchase confirmation email.
Click Activate License.
A green check confirms that your license is active.

Managing an Active License

Once active, the key is masked on screen as ••••••••XXXX for privacy. Use Show key to reveal it temporarily (auto-hides after 10 seconds), or Replace key to swap it for a different one.
To deactivate, click Deactivate License. This frees the activation slot in your account so you can use the key on a different site.
If you change the site’s domain (e.g. moving from staging to production), the plugin automatically deactivates on the old domain. Re-activate from the same screen on the new host.

Recovery Options

If the licensing server is unreachable or the local state ever gets out of sync, use the Force Local Deactivation button at the bottom of the License tab. This clears the local state without contacting the server.
The activation slot in your account may need to be released manually from your account dashboard if Force Local Deactivation was used.
For support tickets, the License tab includes a Diagnostics — last proxy exchange panel at the bottom. Copy and paste its contents into your support email and we can debug activation issues remotely.

Note: Without a valid license, the field and widgets will not render on the front-end. Activation is also what enables automatic plugin updates.

Adding Icons to AECI

There are three ways to make icons available in the picker. You can use any combination of them.

Option 1: Font Awesome 6 (Always Available)

Font Awesome 6 is bundled with the plugin. No setup required.
Every editor sees all FA Solid, Regular and Brands icons in the picker automatically.

Option 2: Custom Icon-Font Sets (IcoMoon / Fontello)

Custom icon-font sets are uploaded through Elementor’s own custom icons screen and auto-detected by AECI.

Prepare your icon font files using a tool like IcoMoon or Fontello. Make sure the export contains selection.json (IcoMoon) or config.json (Fontello) at the root.
In the WordPress admin, navigate to Elementor > Custom Icons.
Click Add New and upload your icon set ZIP.
Provide a name for your icon set and save.
Your icons are now available for selection in the AECI picker, alongside Font Awesome.

Note: The “Custom Icons” screen is provided by Elementor Pro, not by this plugin. AECI auto-detects every set uploaded there.

Option 3: Custom SVG Uploads (New in 2.0)

If you want to use individual SVG files — from libraries like Heroicons, Phosphor, Lucide, Tabler Icons, or your own designs — upload them directly through the AECI SVG Library.

Go to Settings > AECI Custom Icons and click the SVG Library tab.
Click Choose Files, select one or multiple .svg files (up to 250 KB each).
Click Upload.
Each uploaded SVG is automatically sanitized — scripts, event handlers, and external references are removed for safety. Files are stored under wp-content/uploads/elementor/custom-icons/aeci-svg/.
Uploaded SVGs appear in the picker under the Custom SVGs tab. To remove an SVG, click Delete on its card in the SVG Library.

Tip — using third-party icon libraries: download the official ZIP from the project (Heroicons, Phosphor, Lucide, Tabler, etc.), unzip locally, and bulk-upload the SVG files you want through the form (multi-select is supported). For best results with the Color widget control, use icons authored as monochrome — the plugin forces fill="currentColor" on the SVG root so it inherits the widget’s color.

Using the ACF Custom Icon Field

Step 1: Create or Edit a Field Group

Go to Custom Fields > Field Groups.
Click on Add New or edit an existing field group.

Step 2: Add a Custom Icon Field

Click Add Field.
Set the Field Label (e.g. “Icon Selection”).
For Field Type, select Custom Icon.

Step 3: Configure Icon Sets

In the field settings, tick which icon sets should be available in the picker for this field: Font Awesome, Custom SVGs, and any custom icon-font set you have uploaded.
Adjust any additional ACF settings as needed (conditional logic, required status, etc.).

Step 4: Assign the Field Group

Set the location rules to determine where this field group appears.
Click Publish or Update.

Step 5: Use the Field in Posts or Pages

When editing a post or page where the field group is assigned, you’ll see the Select Icon button.
Click it to open the icon picker — a fast, searchable grid that handles thousands of icons smoothly.
Use the Recent strip at the top to re-select recently used icons quickly.
Use the search box (or press / to focus it) to filter by icon name.
Switch between icon sets using the tabs at the top of the picker.

Keyboard shortcuts in the picker: / focuses the search, arrow keys navigate the grid, Enter selects, Esc closes.

Using the AECI Dynamic Icon Widget

AECI Dynamic Icon is the recommended widget for new projects. It handles every supported ACF field type from a single widget. The three legacy widgets (ACF Custom Icon, ACF Flexible/Repeater Custom Icon, ACF Taxonomy Term Custom Icon) remain available for backwards compatibility and are clearly marked as Legacy in the panel.

Step 1: Open Elementor Editor

Edit the page or template where you want to display the icon.

Step 2: Add the Widget

In the Elementor widget panel, search for AECI Dynamic Icon.
Drag and drop it into your layout.

Step 3: Configure the Content Tab

Field Type: choose Simple, Group, Repeater, Flexible Layout, or Taxonomy Term based on where your icon is stored.
ACF Field Name: type the name of your custom_icon field (e.g. icon_main). For Group fields, also fill in the Sub Field Name.
If your site has detected ACF custom_icon fields, you can toggle Pick field from list to switch from manual typing to a dropdown of all detected fields — useful when you have many fields and want to avoid typos.
Field Source: choose between current post/page or an Options Page.
Link: optionally wrap the icon in a link.

Step 4: Style the Widget

Switch to the Style tab to configure alignment, color, size, rotate, animation, container background, border, padding, border radius and box shadow.
Use the Hover sub-tab for hover-state color, background, scale, rotate, transition and box shadow.

Note for Repeater and Flexible Content: place the widget inside the loop (Loop Grid template, Listing template, etc.). The widget reads the icon via get_sub_field() first and falls back to get_field() outside loops.
Note for Taxonomy Term: the widget works inside Elementor Pro Loop Grid, JetEngine Listing Grid, or directly on a taxonomy archive page.

Hover Swap Icon (New in 2.0)

Display a different icon when the user hovers the widget — useful for navigation menus, social links, CTAs and feature cards.

Setting Up a Static Hover Icon

Edit your AECI Dynamic Icon widget.
In the Content tab, expand the Hover Icon section.
Toggle Enable hover swap on.
Choose any icon from any installed set in the Hover icon picker.
Adjust the Transition duration slider (default 0.2 seconds).

Setting Up a Dynamic Hover Icon (from another ACF field)

The AECI Dynamic Icon widget can read the hover icon from a second ACF custom_icon field on the same record — useful for setups where each item has both a default and hover icon stored side by side.

Make sure your record has two custom_icon fields, one for the default state and one for hover (e.g. icon_main and icon_hover).
In the widget’s Hover Icon section, after enabling the toggle, set Hover icon source to From another ACF field.
Type the name of the hover field in Hover icon ACF field (e.g. icon_hover).

Note: Dynamic hover from another field reuses the same Field Type as the main icon (Simple, Repeater, Flexible, Taxonomy). The Group field type is intentionally not supported here — use the static picker if your record uses Group fields.

Editor Preview (New in 2.0)

When the widget can’t resolve a real icon in the Elementor editor — for example inside a Loop Grid template not bound to a specific post, or inside a repeater layout outside its loop — Elementor would normally show an empty placeholder. The Editor Preview lets you display a static icon in the editor only, without affecting the front-end.

Enabling Editor Preview

Edit your AECI Dynamic Icon widget.
In the Content tab, expand the Editor Preview section.
Toggle Use editor preview icon on.
Choose any Font Awesome icon as your editor placeholder.

Note: the preview icon is only ever shown inside the Elementor editor canvas. The front-end resolves the real icon dynamically as always.

Animations (New in 2.0)

The widget includes 9 built-in CSS animations that can be applied per widget.

Open the Style > Icon section of your widget.
From the Animation dropdown, choose one of: Spin, Pulse, Beat, Shake, Fade, Bounce (Font Awesome animations), or Spin / Pulse / Bounce (universal — work on any icon set).

Note: Font Awesome animations only apply to FA icons. Universal animations work on any icon set, including custom IcoMoon / Fontello fonts and uploaded SVGs.

Dynamic Tags (New in 2.0)

Any Elementor control that accepts a dynamic ICONS source can read its value from an AECI custom_icon field — so you can use Elementor’s native widgets (Icon List, Icon Box, Social Icons, Buttons, etc.) and pull the icons from your ACF data.

In the Elementor editor, click the dynamic icon (the small lightning bolt) next to any ICONS control.
Choose AECI: ACF Custom Icon.
Configure the same Field Type, Field Name and Source as you would in the AECI Dynamic Icon widget.

Rendering Icons in Custom Theme Code

If you want to display an AECI icon outside of Elementor — for example inside a custom PHP template or a shortcode — use the helper function:

echo aeci_render_icon( get_field( 'icon' ) );

The helper takes care of font-vs-SVG detection, classname sanitization and asset enqueueing automatically. It accepts either the JSON value stored by the ACF field or a parsed array.

Font Awesome Integration

The plugin includes the full Font Awesome 6 library, expanding your icon selection significantly.

Using Font Awesome Icons:

In the ACF Custom Icon field or AECI Dynamic Icon widget, Font Awesome icons are available alongside your custom icons.
Switch to the Font Awesome tab in the picker.
Search for the desired icon by name or browse through Solid, Regular and Brands variants.

Note: Font Awesome 6 is bundled with the plugin. No CDN connection is required, and no internet connection is needed to use the icons after installation.

Updates and Support

Receiving Updates

With an active license, your site checks for plugin updates automatically.
When a new version is available, you’ll see the standard WordPress update notification on the Plugins screen.
If you don’t see a recent update right away, this is normal — WordPress caches the update check for up to 12 hours. To force an immediate check, go to Dashboard > Updates and click Check Again.

Getting Help

For support, contact us through the product page.
When reporting an issue, include the contents of the Diagnostics — last proxy exchange panel from the License tab. It contains the most recent licensing-server response and helps us debug remotely.