Documentation

Everything the field does, in one page.

From installing the plugin to rendering an icon in a template — requirements, configuration, the get_openicon() API, ACF blocks, custom SVGs and migration.

WordPress 5.0+PHP 7.4+ACF Free or Pro 5.0+

01 — Requirements

What the plugin needs.

WordPress 5.0 or higher
PHP 7.4 or higher (PHP 8.0+ recommended)
Advanced Custom Fields Pro or ACF Free (version 5.0+)
A valid licence key for the Pro features — the free plugin runs without one

02 — Installation

Four steps, either edition.

The free plugin comes from WordPress.org; Pro is the ZIP that came with your purchase email. Everything after this section is identical on both.

Install ACF first

Open Icons is a field type, not a standalone plugin. ACF Free or ACF Pro 5.0 or higher has to be installed and activated before the field appears.

Get the plugin

Free: search for Open Icons in Plugins > Add New. Pro: download the ZIP from your purchase email, then Plugins > Add New > Upload Plugin.

Activate

Click Activate. If you are moving from free to Pro, activating Pro deactivates the free plugin for you — Pro contains everything it had, so there is nothing to clean up.

Configure

Go to Custom Fields > Open Icons. Pro users paste the licence key here. On free there is nothing to activate — add the field to a field group and start picking.

03 — Configuration

One settings screen.

Everything below lives at Custom Fields > Open Icons.

Licence activation

Navigate to Custom Fields > Open Icons in WordPress admin
Enter your licence key in the License section
Click Activate License
Once activated, all plugin features will be available

Icon set selection

Go to Custom Fields > Open Icons
In the Icon Set section, select your preferred icon library:
- Lucide — modern, consistent icon set
- Tabler Icons — comprehensive icon collection
- Heroicons — hand-crafted SVG icons
Optionally pin a specific version for stability
Click Save Changes

Colour palette

Configure colour tokens that can be applied to icons. A token is a name, not a value — change the palette and every icon using that token changes with it.

Token AToken BToken C

In the Palette section, set colours for tokens A, B and C
These tokens can be applied when selecting icons
Changing palette colours automatically updates all icons using those tokens

Passing color to get_openicon() bypasses the token and forces that value for a single call.

04 — Usage

One helper function.

Add the field, then render it with get_openicon(). The SVG is written into your markup by PHP before the page is sent.

Creating an ACF field

Go to Custom Fields > Field Groups
Create a new field group or edit an existing one
Add a new field and select Open Icons as the field type
Configure field settings (label, name, required, and so on)
Save the field group

What the field stores

The field value is an array: which library, which name, which colour token, and the rendered SVG. Nothing lands in the media library and there is no attachment to manage — the icon travels with the field.

// return format: array
{
  "provider":   "lucide",
  "version":    "0.544.0",
  "iconKey":    "calendar-days",
  "colorToken": "A",
  "svg":        "<svg …></svg>"
}

Pass that array straight to get_openicon(). It has to be the array — a bare icon-name string renders nothing.

Basic usage

<?php
$icon_field = get_field('icon_field');

// Basic usage (default size: 24px)
get_openicon($icon_field);

With custom size

<?php
$icon_field = get_field('icon_field');

// With custom size
get_openicon($icon_field, [
    'size' => 32, // default: 24
]);

Return instead of echo

<?php
$icon_field = get_field('icon_field');

// Return instead of echo
$svg_markup = get_openicon($icon_field, [
    'size' => 64,
    'echo' => false,
]);
echo $svg_markup;

With colour override

<?php
$icon_field = get_field('icon_field');

// With color override (bypasses token-based color)
get_openicon($icon_field, [
    'size'  => 48,
    'color' => '#a7f3d0',  // Force a specific color
]);

This bypasses token-based colour and forces a specific value.

With CSS classes

<?php
$icon_field = get_field('icon_field');

// With CSS classes
get_openicon($icon_field, [
    'class' => 'icon-class-name',
    'size'  => 32,
]);

05 — Parameters

get_openicon( $value, $atts )

Two arguments. The second is optional and takes four keys.

$valuearray

The icon field value from ACF, passed through as-is. Anything that is not an array renders nothing.

$atts['size']int

Icon size in pixels. Default 24.

$atts['color']string

Hex colour override. Bypasses token-based colour.

$atts['class']string

CSS class name(s) to add to the SVG.

$atts['echo']bool

Whether to echo or return the markup. Default true.

06 — ACF blocks

Icons inside a block.

Open Icons fields work inside ACF blocks. Register the block as normal with acf_register_block_type(), attach a field group containing an Open Icons field to that block, then render the selected icon from your block callback or template.

functions.php — feature block

<?php
add_action('acf/init', function () {
    if (! function_exists('acf_register_block_type')) {
        return;
    }

    acf_register_block_type([
        'name'            => 'openicon-feature',
        'title'           => __('Feature with Icon', 'open-icons-acf'),
        'description'     => __('Feature item with an Open Icons field and text.', 'open-icons-acf'),
        'render_callback' => 'openicons_render_feature_block',
        'category'        => 'widgets',
        'icon'            => 'star-filled',
        'keywords'        => ['icon', 'feature', 'open icons'],
        'supports'        => [
            'align' => ['wide', 'full'],
            'anchor' => true,
            'jsx' => true,
        ],
    ]);
});

function openicons_render_feature_block($block): void
{
    $icon  = get_field('feature_icon');
    $title = (string) (get_field('feature_title') ?: '');
    $text  = (string) (get_field('feature_text') ?: '');

    $classes = 'oi-feature';
    if (! empty($block['className'])) {
        $classes .= ' ' . sanitize_html_class($block['className']);
    }

    echo '<article class="' . esc_attr($classes) . '">';

    if ($icon) {
        echo '<div class="oi-feature__icon" aria-hidden="true">';
        get_openicon($icon, ['size' => 24, 'class' => 'oi-feature__icon-svg']);
        echo '</div>';
    }

    echo '<div class="oi-feature__content">';

    if ($title !== '') {
        echo '<h3 class="oi-feature__title">' . esc_html($title) . '</h3>';
    }

    if ($text !== '') {
        echo '<p class="oi-feature__text">' . esc_html($text) . '</p>';
    }

    echo '</div></article>';
}

The icon key in the registration array controls the icon shown in the block inserter. Your Open Icons field still comes from the ACF field group assigned to the block.

07 — Migration

Switching icon library.

The field records which library and which name, so moving from one library to another is a remap, not a re-upload. The migration tool finds every icon in use, groups them by name and rewrites them in one pass.

Migrating between icon libraries

Go to Custom Fields > Open Icons
Navigate to the Migration section
Review icons that need migration
Use the migration tool to match and update icons to the new library

08 — Custom icons

Your own SVGs, sanitised on the way in.

Alongside the built-in libraries you can upload your own SVG icons — brand marks, custom illustrations, any SVG graphic you need.

Uploading

Navigate to Custom Fields > Open Icons in your WordPress admin
Scroll to the Custom Icons section
Click the upload area or drag and drop your SVG file(s)
Your icons will be sanitised and stored securely

Storage location

Custom icons are stored in your WordPress uploads directory:

/wp-content/uploads/open-icons-acf/custom/

Icons are sanitised before storage to remove potentially harmful content while preserving visual fidelity.

The Pro icon cache

Lucide and Tabler are fetched from jsDelivr the first time you pick an icon, then cached alongside your custom icons:

/wp-content/uploads/open-icons-acf/cache/

It is a cache, so it is safe to delete — the next pick rebuilds what it needs. Rendering never touches it: the SVG in your field data is what goes into the page.

Using custom icons

Once uploaded, custom icons appear in the picker as another library, alongside the built-in ones. They behave the same way:

Select Custom from the library dropdown in the icon picker
Search and browse your uploaded icons
Apply colour tokens just like any other icon
Use the same get_openicon() helper in your templates

Managing custom icons

View all uploaded icons with their file sizes and upload dates
Delete icons you no longer need
Icons that are deleted but still referenced in fields will be marked as orphaned

Deleting a custom icon does not remove it from fields where it has been selected. Use the migration tool to update affected fields.

09 — Updates

Updates arrive in the Plugins screen.

Updates are checked daily via WordPress cron
Update notifications appear in the Plugins page
Updates require a valid licence (active or within the grace period)
Updates are delivered securely via a proxy endpoint with licence validation

Still stuck?

Install it, then ask us anything.

The free plugin ships 324 Heroicons. Pro is a licence key you paste into wp-admin, not an account to create. If something in here does not match what you are seeing, tell us.

Install free See pricing