ACF Elementor Custom Icon Picker

A WordPress plugin that adds an ACF field type for picking icons from Elementor's Custom Icon libraries (the icon sets you upload in Elementor → Custom Icons), and a matching Elementor widget to render them.

How it works

You get four things:

1. ACF field type — Elementor Custom Icon — a searchable grid showing every icon from every custom icon library installed via Elementor.
2. Elementor widget — ACF Custom Icon — drop it on any page, point it at one of your ACF fields, get full styling controls (color, size, hover, link, etc.).
3. Dynamic Tag — usable inside Heading / Text Editor / any text widget to output raw <i> HTML.
4. Shortcode — [aeip_icon field="my_icon"] — for non-Elementor contexts.

Why a widget instead of just a dynamic tag? Elementor's built-in Icon widget doesn't expose dynamic-tag pickers on its icon control, so a dynamic tag alone isn't enough. The widget is the proper integration: drop it in, point it at a field, style it however you want.

Requirements

• WordPress 5.8+
• PHP 7.4+
• Advanced Custom Fields (free) or ACF Pro
• Elementor (free works; Pro is needed if you want to upload custom icon sets via Elementor → Custom Icons — otherwise use a free plugin like Custom Icons for Elementor)
• At least one custom icon library uploaded to Elementor

Usage

1. Add the ACF field

ACF Field Group → Add Field → choose Elementor Custom Icon (under Choice).

2. Pick an icon when editing a post

The field shows a searchable, filterable grid of every icon from every Elementor custom icon library. Filter by library, search by name, click to select.

3a. Render in Elementor (recommended)

Edit a page → search the widget panel for ACF Custom Icon → drag it in. In the Icon section:

• ACF Field — pick which field to read from (groups & repeaters are walked automatically)
• Field Source — auto (current post or term) / Options page / specific post ID / specific term ID
• Fallback Icon Class — optional, used when the field is empty

Taxonomy terms: With Field Source → Auto, the widget detects the current term on taxonomy archives and inside Elementor Pro taxonomy loops (via $wp_query->loop_term). Use Specific Term ID to target a term from anywhere else.

The Style tab gives you color, hover color, size, rotation, padding, border, border radius, box shadow, alignment, and a link control.

3b. Render via Dynamic Tag (text widgets only)

Inside a Heading or Text Editor widget, click the dynamic-tag icon next to a text control → ACF Custom Icons → ACF Custom Icon. Outputs <i class="..."> HTML.

Note: This won't appear in the regular Icon widget — Elementor's free Icon widget doesn't accept dynamic tags on its icon control. Use the widget from option 3a instead.

3c. Render via Shortcode

[aeip_icon field="my_icon"]
[aeip_icon field="my_icon" size="48px" color="#ff0044" tag="span"]
[aeip_icon field="my_icon" post_id="42"]
[aeip_icon field="my_icon" post_id="option" fallback="fas fa-star"]
[aeip_icon field="cat_icon"]                      (auto-detects current term on a taxonomy archive)
[aeip_icon field="cat_icon" term_id="15"]         (specific term from anywhere)
[aeip_icon field="cat_icon" term="term_15"]       (ACF-style term identifier)

Taxonomy terms: When the shortcode is used on a category/tag/custom-taxonomy archive, it auto-detects the current term via get_queried_object(). Inside Elementor Pro taxonomy loops, it reads the loop item from $wp_query->loop_term automatically. To render a term icon elsewhere, use term_id="15" or term="term_15". You can also pass post_id="term_15" if you prefer.

3d. Render in PHP (theme code)

$icon = get_field( 'my_icon' );
if ( $icon ) {
    echo $icon['html']; // <i class="foobar foobar-home"></i>
}

// or just the class:
echo esc_attr( $icon['class'] );

The field's Return Format (configurable per field) controls what get_field() returns: array (default), class (just the string), or html (the full <i>).

How icons are detected

Elementor exposes every custom icon library through its elementor/icons_manager/additional_tabs filter. That's how Elementor Pro's own Custom Icons feature publishes its libraries, and the same hook is used by third-party plugins (e.g. Custom Icons for Elementor).

This plugin reads from that filter, then fetches each library's icon list from its fetchJson URL (the JS metadata file that Elementor's editor itself fetches). Results are cached in a transient for an hour, and the cache is auto-flushed when you save or delete a custom icon set.

The CSS for every custom library is enqueued automatically on the front-end so icons always render — no manual setup needed.

Troubleshooting

ACF field shows "No custom icon libraries detected"

• Make sure Elementor Pro is active (or that you're using a free plugin to upload icon sets).
• Make sure your icon set is Published, not Draft, in Elementor → Custom Icons.
• Refresh the post editor — the icon list is cached for an hour, but cache is auto-flushed when you save an icon set.

Widget shows but no icon renders on the front-end

• Verify the ACF field has a value saved on that post.
• Check the page source for the <i class="..."> — if the class is right but the icon doesn't show, the icon font CSS isn't loading. Hard-refresh / clear cache.

Widget doesn't appear in Elementor panel

• Search "ACF Custom Icon" in the widget panel. It's under the General category.
• Make sure both Elementor and ACF are active.

File structure

acf-elementor-icon-picker/
├── acf-elementor-icon-picker.php           # Main plugin bootstrap
├── includes/
│   ├── class-aeip-icons-source.php         # Reads Elementor icon libraries
│   ├── class-aeip-object-resolver.php      # Resolves post/term/options ACF object ids
│   ├── class-aeip-acf-field.php            # ACF custom field type
│   ├── class-aeip-elementor-widget.php     # Elementor widget (primary)
│   └── class-aeip-dynamic-tag.php          # Elementor dynamic tag (text)
├── assets/
│   ├── css/acf-field.css
│   └── js/acf-field.js
└── README.md