Woracious – Premium WordPress themes and plugins

Choosing the Right Icon for Your ACF Block in Gutenberg (2025 Edition)

Modernizing WordPress block icon customization with SVGs, Dashicons, and beyond

If you’re building custom blocks with ACF (Advanced Custom Fields) in 2025, chances are you’ve wanted to add a fitting icon to your block to make it visually stand out in the Gutenberg editor. The challenge? Finding the right icon format — and knowing where to get those icons.

Let’s walk through how to add icons to your custom ACF blocks the modern way, what your options are in 2025, and why choosing the right icon approach matters for both clarity and user experience.

💡 Why Block Icons Matter

When building a custom Gutenberg block, the icon you assign:

  • Appears in the block inserter UI
  • Helps users recognize your block at a glance
  • Reinforces your brand or design system

But icon handling in WordPress can feel like a moving target: Dashicons, inline SVGs, and now a full React icon library.

🛠️ Three Ways to Add Icons to ACF Blocks (and When to Use Them)

1. Use Dashicons by Name (Old School, Still Works)

If you want quick and easy, Dashicons are still supported. These are the original WordPress icon font.

'icon' => 'admin-site-alt3', // Dashicon slug

✅ Great for simplicity
❌ Limited design options; not all icons are available

Reference: Dashicon Cheat Sheet

2. Inline SVG Icons (Best for Full Control)

If you’re using ACF PHP registration, you can directly paste an SVG icon’s markup. This method gives you complete freedom over your icon’s look.

🔁 Example: Registering a “Project Showcase” Block with a Custom SVG Icon

add_action('acf/init', 'register_acf_project_block');

function register_acf_project_block() {
    if (function_exists('acf_register_block_type')) {
        acf_register_block_type([
            'name'              => 'project-showcase',
            'title'             => __('Project Showcase'),
            'description'       => __('Highlight a portfolio project.'),
            'render_template'   => 'template-parts/blocks/project-showcase.php',
            'category'          => 'media',
            'icon'              => '<svg width="24" height="24" viewBox="0 0 24 24"><path d="M4 4h16v2H4V4zm0 4h10v2H4V8zm0 4h16v2H4v-2zm0 4h10v2H4v-2z"/></svg>',
            'keywords'          => ['portfolio', 'project', 'showcase'],
        ]);
    }
}

✅ Perfect for branding and full design control
❌ You’ll need to get or create your SVGs manually

Tip: Grab icons from WordPress Icon Library or tools like Heroicons or Feather.

3. Custom Icons via CSS (Rare in 2025, but Possible)

Some devs still attach a custom class and add the icon with background CSS. While functional, this is dated and not recommended unless you’re styling something unique or backwards compatible.

'icon' => 'custom-class-name',

Then in CSS:

.custom-class-name {
    background-image: url('/wp-content/themes/yourtheme/assets/icons/custom-icon.svg');
    background-size: contain;
    background-repeat: no-repeat;
}

✅ Can integrate with legacy styling
❌ Not editor-native; fragile in modern block editors

📋 Developer Checklist

  • ✅ Choose between Dashicons, inline SVG, or React-based icons
  • ✅ Test the icon inside the block inserter
  • ✅ Keep SVGs optimized (tools: SVGOMG)
  • ✅ Use accessible, descriptive markup (aria-labels if needed)

🔗 Bonus Resources

💬 Final Thoughts

In 2025, Gutenberg is more powerful and visual than ever — and icons play a small but crucial role in user experience. Whether you’re building blocks for clients or your own portfolio, don’t overlook this detail.

SVGs offer the most flexibility and future-proofing, but if you’re in a hurry, Dashicons will still do the trick.

Need help optimizing SVGs or creating a custom block icon strategy? Drop a comment or ping me on Mastodon/X/GitHub!

Posted

in

by

subtlekiss

Tags: