DEV Community: WPVibes

Complete Guide to Elementor v4 Components

WPVibes — Wed, 30 Sep 2026 07:24:51 +0000

Think about the last card, testimonial, or CTA block you built that turned out exactly right, then needed to appear on a second page, a third, and a fourth. Did you copy and paste it every time, rebuild it from scratch, and hope nobody quietly changed the padding on one copy while leaving the rest untouched?

Elementor v4 Components exist for exactly this moment. Build the block once, drop it anywhere on the site, and when the original design changes, every copy updates with it. For that one copy that genuinely needs to break the pattern, say a product that's gone out of stock, you can detach just that single copy and edit it freely, without disturbing anything else.

This guide walks through building your first Component, letting each copy show different content, reusing it across the site, and knowing when to detach a copy instead of forcing it to stay in sync. The running example throughout is a Verdure product card, built once and reused across the site, with one copy detached for an out-of-stock product.

Before You Start

Elementor v4.0 or later. Components are a v4 feature.
Elementor Pro. Components require Pro. The free version does not include this feature.
Admin permissions. Only admins can create or edit Components.
Atomic elements only. V3 (classic) widgets cannot go inside a Component.

💡
Notes: We assumes that you already have Variables and Classes set up. If you haven't, start with the Complete Guide to Elementor v4 Variables and the Complete Guide to Elementor v4 Classes first. Components sit on top of everything you build there.

What Is a Component, and How Is It Different from a Global Widget?

A Component is a reusable design block. Its structure and styling stay synced everywhere you use it, but specific content fields inside it, like a product name or an image, can be exposed so each copy shows something different. When one copy genuinely needs to break the pattern, you can detach it and edit it freely without affecting any of the others.

Elementor already had something similar called a Global Widget. Here's how the two compare:

	Global Widget	Component
Design	Same everywhere	Same everywhere
Content	Same everywhere	Different per copy
Want to change something on just one copy?	You have to unlink it, which breaks the connection to the others forever, even for a small text change	Small content changes (text, image, price) are built in, no unlinking needed. For a bigger change (like disabling a button), you can detach just that one copy
Best for	Things that should always look and say the exact same thing, like a floating CTA banner	Cards, testimonials, anything that shares a design but needs different content

For most real work, product cards, service cards, testimonials, Components are the better fit.

How Do You Build Your First Component?

Building a Component happens in two parts: you design it like any normal element, then you mark the fields that should vary from copy to copy.

Build the design

Start on any page. Add a Div block or Flexbox container as the outer wrapper, since every Component needs one.
Inside it, add your atomic elements. For the Verdure card that's an Image element for the product photo, a Div block for the body, and inside that a Paragraph for the rating, a Heading for the product name, another Paragraph for the price, and a Button for Add to Cart.
Style it exactly the way you want every copy of this card to look.

Turn it into a Component

Right-click the wrapper Div block and choose Create component.
Name it something meaningful, for Verdure that's product-card, and click Create.
Elementor processes this for a moment, then drops you into Component editing mode, a special view for working on the original design.

Check out the video of converting design into components.

💡
Tips: If your site also runs Contact Form 7, Elementor Forms, Gravity Forms, or Ninja Forms, enable all of them at once. All submissions appear in the same Form Vibes dashboard - no need to switch between plugins.

How Do You Expose Editable Properties?

Right now, every copy of this Component would show identical content: same photo, same name, same price. To let each copy differ, you expose specific fields as properties.

While still in Component editing mode, click the element you want to make editable, say the product image, and look for a small diamond icon next to its setting in the panel.

Click it, give the property a clear name, and confirm. That field is now exposed, and every future copy will let editors change it.

Check out the video of exposing editable properties.

A typical Verdure product card exposes:

Product image
Product name
Current price (and old price, if you show a strikethrough)
Star rating
Button link
Badge text ("Bestseller," "New," and so on)

Everything else, padding, colors, borders, hover animation, stays locked to the original design.

Once you're done, click outside the editing overlay to return to your normal page editor.

How Do You Reuse a Component Across Your Site?

Once created, your Component shows up in its own Components tab in the widget panel, right next to the regular Elements tab.

To place more copies, drag the Component from that tab wherever you need it.

Click on a copy, and the settings panel now shows only the properties you exposed, not the full list of every style setting, so editors can't accidentally break the design while filling in content.

Fill in the product photo, name, price, rating, link, and badge for each copy, and repeat for as many products as you need.

Every copy looks visually identical but can show completely different content. That is the entire point.

All of these copies stay synced to the original design. Go back into Component editing mode and change the border radius or padding, and every copy updates instantly. Content stays per-copy. Structure and style stay shared.

When and How Do You Detach a Component?

Here's a real scenario. You need another product card on the homepage, but this product is out of stock. It should look like the other cards but show a disabled "Out of Stock" button instead of a clickable "Add to Cart" one, greyed out, non-clickable, different text.

This isn't a content change you can solve by editing a property. Whether a button is clickable at all is a structural difference, and it only applies to this one card. The fix is to detach just this one instance from the original design.

💡
Important: Detaching is permanent. Once you detach a copy, it stops receiving any future changes made to the original design, and there is no way to reconnect it. Only detach a copy once you're sure you want it to stop following the original forever.

Detaching breaks the sync between that one copy and the original design, permanently. The copy keeps its current look, but becomes a normal set of elements you can edit freely from then on. Any future changes to the original design will simply not reach it anymore.

To detach:

Right-click the copy you want to break away.
Choose Detach from Component.
Confirm the action.

From there it behaves like any other element on the page: change the button text, swap its background, remove the link so it isn't clickable, and add anything extra you need, like a "Notify me when back in stock" link.

Increase the padding on the original design later, and every synced card picks up the change automatically. The detached out-of-stock card stays exactly as it was, because it no longer listens to the master.

Should You Expose a Property or Detach?

The most common mistake with Components is reaching for the wrong tool between these two.

Expose a property when	Detach when
The variation is only content: text, an image, a link	The variation is structural: adding or removing elements, changing behavior
It's likely to repeat across several copies	It's a genuine one-off, not a repeating pattern
You want future changes to the original design to keep reaching this copy	You're fine with this copy no longer receiving those changes
Example: a different product name and price per card	Example: the out-of-stock card with a disabled button

Get this wrong in either direction and it costs you. Detach too easily and your site fills up with copies that quietly miss every future design update. Refuse to detach when you should and you end up with one overloaded Component full of conditional properties trying to do the job a clean detach would have solved in one click. Most copies on a real site should stay synced. Detach is the exception, not the default.

What Mistakes Should You Avoid?

Building Components before your design system is stable. If your Classes and Variables are still changing, every design tweak becomes a Component update too. Settle those first (see the Complete Guide to Elementor v4 Design System), then build Components on top.
Placing copies before exposing properties. If you drop several copies on the site before exposing any properties on the original design, all of them show identical content. Finish the original design first.
Detaching when you should have exposed a property. If you find yourself detaching several copies just to change the same field, that field should have been an exposed property instead.
Forgetting what detaching costs you. Once detached, a copy stops receiving those changes. If a redesign happens later, every detached copy will visibly fall behind.
Using V3 widgets inside a Component. Components only support V4 atomic elements. A classic widget dropped inside simply won't work. Rebuild it with the atomic equivalent instead.

Frequently Asked Questions

Do Elementor v4 Components work in Elementor Free?

No. Components require Elementor Pro.

Can I use Components with V3 (classic) widgets?

No. Components only support V4 atomic elements. Your existing V3 widgets keep working elsewhere on the site, but they can't be placed inside a Component.

What is the difference between a Component and a Global Widget?

A Global Widget shows the same design and the same content everywhere, and changing content on one copy means unlinking it, which permanently breaks the sync. A Component shows the same design everywhere but lets you expose specific content fields so copies can differ, without ever breaking the sync.

How do I know if a Component has been detached?

You can't tell just by looking. A detached copy becomes a regular set of elements with no visible marker that it was ever a Component. On larger sites with several editors, it's worth keeping your own note of what's been detached.

Can I re-attach a detached copy to its Component?

No. Detaching is one-way. If you want a copy back in sync with the original design, delete it and drop in a fresh copy of the Component instead.

How many properties can I expose on one Component?

There's no hard limit, but keep it practical. A Component with too many exposed properties becomes confusing to fill in. If you're exposing a lot, it may be worth splitting it into two smaller Components instead.

Do original design updates reach copies immediately?

Yes, for every synced copy across the site. Detached copies are the one exception, they stop receiving updates the moment they're detached.

Wrapping Up

Variables give you tokens. Classes give you reusable styling bundles. The Design System panel gives you visibility over both. Components give you reusable design blocks, the piece that turns all of it from theory into something you actually build with. Design a card once, reuse it everywhere, update the original design when the brand changes, and detach the rare one-off that genuinely needs to break the pattern.

The takeaways:

Components are reusable design blocks with per-copy content. The natural next step after Variables and Classes.
Expose properties for content that varies: text, images, links, prices.
Detach only for structural, one-off changes, knowing you give up future changes to the original design in exchange.
Most copies should stay synced. Detach is the exception, not the default.
Components complete the Elementor v4 design system: Variables, Classes, the Design System panel, and Components.

Complete Guide to Elementor v4 Design System

WPVibes — Thu, 24 Sep 2026 06:44:39 +0000

As your website grows, keeping its design consistent can become difficult.

The same colors, fonts, spacing, buttons, and other styles may be used across many pages. If these styles are managed separately, even a small design change can require updating multiple elements manually.

A design system helps solve this problem by keeping commonly used design values and styles organized and reusable.

In Elementor v4, Variables and Classes help you build this system, while the Design System panel gives you one place to view and manage them.

In this guide, we’ll look at how the Elementor v4 Design System works and how you can use it to manage your website more easily.

What Do You Need Before Using the Design System?

Elementor v4.0 or later, the Design System panel is a v4 feature
Elementor v4.1 or later for the unified Design System panel this article focuses on. Classes and Variables existed from v4.0 onward, but they lived in two separate managers until v4.1 combined them into one panel.
Elementor Free or Pro, the panel is available in both, but Pro is needed to view Variables (Free users see Classes only)
Any WordPress theme

Why Use a Design System in Elementor?

On a small website, manually managing styles may work fine. But as you add more pages and elements, it becomes easier for the design to become inconsistent.

For example, you may end up with:

Different shades of the same brand color
Slightly different button styles
Inconsistent heading sizes
Different spacing between similar sections

A design system gives you reusable values and styles that you can use throughout the website.

This helps you:

Keep the design consistent
Reuse existing styles
Make site-wide changes more easily
Keep design settings organized as the website grows

Instead of styling every element separately, you create common design values and styles once and reuse them wherever needed.

How Does the Elementor v4 Design System Work?

Elementor v4 mainly uses Variables and Classes to create a reusable design system.

Variables

Variables store reusable values such as colors, typography, and sizes.

For example, you can create a Variable called color-primary for your main brand color and use it across buttons, headings, backgrounds, and other elements.

If you change the Variable later, elements using it can use the updated value.

For a detailed walkthrough, read our Complete Guide to Elementor v4 Variables.

Classes

Classes store reusable groups of styles.

For example, a btn-primary Class can contain the background color, text color, padding, border radius, and hover styles for your primary buttons.

You can apply the same Class to multiple buttons instead of styling each one separately.

Learn more in our Complete Guide to Elementor v4 Classes.

Together, Variables and Classes form the foundation of your Elementor design system.

What Is the Elementor v4 Design System Panel?

The Design System panel is a dedicated view inside Elementor v4 that displays every Variable and every global Class registered on your site in one screen. It does not add new capabilities. It gives you visibility and control over the system you have already built.

Three things become possible once you use it regularly:

See everything in one place: No need to open the Variables Manager, then separately open the Class Manager, just to find a color you set up weeks ago. It is all visible together.
Edit any part from one place: change a color, adjust a Class, update a size, all without leaving the panel.
Present the system as a whole: to clients, teammates, or future you looking back on the project six months later.

Where to Find the Design System Panel

Inside the Elementor editor:

Look at the Top Bar and click the Design System icon.
The panel opens directly, showing your entire system on one screen.

💡
Notes: This panel is a v4.1 addition. If you are on an earlier v4.0 build, you will still have Classes and Variables individually, through the Class Manager and Variables Manager, but not this combined view. Update to v4.1 or later to get the unified panel described in this article.

What Can You Manage in the Design System?

The panel organizes your design settings into different sections.

Colors

The Colors section contains the color Variables used on your website. Using named Variables makes it easier to understand where each color should be used.

color-primary, deep forest green (#0F2F23)
color-primary-dark , hover state (#08201A)
color-accent , warm gold (#C99A3D)
color-text , body text (#24332D)
color-text-muted , secondary text (#6B7770)
color-bg , page background (#FFFFFF)
color-bg-alt , cream background (#FAF6EE)

Typography

The Typography section contains reusable typography values, such as your heading and body fonts.
font-display (Cormorant Garamond), used for headings
font-body (Inter), used for body text
type-h1 through type-small , the full type scale

Sizes

All size-based Variables: spacing, container widths, image dimensions, radius values.

Spacing: space-xs through space-section
Sizes: hero-image-size, product-image-height, container-width
Radius: radius-sm through radius-pill

Classes

Every global Class you have created, with properties visible on click.

Button: btn, btn-primary, btn-accent, btn-outline
Card: card, card-product, card-category, card-benefit, card-blog
Section: section, section-alt, section-dark, section-header
Layout: container, grid-2, grid-3, grid-4
Heading: heading, heading-h1, heading-h2, heading-h3
Text: eyebrow, text-muted

💡
Important: The layered Class pattern covered in the Classes article is visible here: btn handles structure, btn-primary handles appearance. Applied together, they produce a fully styled primary CTA.

How to Use the Design System Panel on a Real Website

The Design System becomes especially useful when you need to make changes or review the styles used across your website.

Workflow 1: Update Your Brand Everywhere in Seconds

Suppose you want to change your primary brand color.

If your website uses a color-brand Variable, you can update that Variable instead of manually changing the color on multiple elements. With the Design System panel:

Open Design System
Click the color-brand swatch
Change the hex value
Save

Every button using btn-primary, every dark section, every heading using color-brand, every accent across every page on the site updates instantly.

Workflow 2: Keep Your Classes Organized

As you build more pages, you may create more Classes. Over time, similar Classes can appear, such as:

btn-primary and btn-primary-new.

Reviewing your Classes helps you find duplicates and reuse existing styles instead of creating unnecessary new ones.

Try to use clear names so you can easily understand what each Class is for.

Workflow 3: Present the System to a Client

When handing a project off to a client or presenting to a designer, screen-share the Design System panel instead of opening several different settings screens. It answers the "what does the brand use?" question in seconds.

For agencies, this might be the single most useful thing about the panel. Design reviews become shorter. Client conversations become clearer. The design system stops being a hidden technical detail and becomes a visible deliverable.

What Mistakes Should You Avoid?

Treating the panel as read-only: The Design System panel is fully editable. Changes save immediately and propagate everywhere. Use it as your primary editing surface for design system work.
Not auditing regularly: Class libraries grow. Open the panel on a regular schedule, delete unused Classes, consolidate duplicates. A short, regular check prevents a much bigger cleanup later.
Building pages without setting up the system first: Some teams start designing and hope to extract Variables later. It rarely works cleanly. Set up your core Variables and a few base Classes before the first page. The rest of the system grows naturally from there.
Skipping the panel during client handoff: The Design System panel answers most "what does the brand use?" questions in one screen. Not showing it during handoff means fielding those same questions over email for weeks afterward.

Frequently Asked Questions

What is the Elementor v4 Design System?

The Elementor v4 Design System brings reusable design values and styles together so they are easier to view and manage.

Does the Elementor v4 Design System panel work in Elementor Free?

Yes, with limits. Free users see the Classes section fully but see no Variables (Variables require Pro). Pro users see everything.

Can I edit Variables and Classes directly from the panel?

Yes. Clicking any Variable or Class opens it for editing inside the panel. Changes save immediately and propagate site-wide.

What is the difference between Variables and Classes?

Variables store reusable values such as colors, fonts, and sizes. Classes store reusable groups of styles that can be applied to elements.

How is the Design System panel different from the Variables Manager and Class Manager?

The Variables Manager shows only Variables. The Class Manager shows only Classes. The Design System panel shows both together in one organized view. Same underlying data - different way of looking at it.

Do I need a design system for a small site?

Not necessarily. A small website may be easy to manage manually. A design system becomes more useful as your website grows and the same styles are reused across multiple pages and elements.

Wrapping Up

The Elementor v4 Design System gives you a more organized way to manage repeated design values and styles.

Variables help you reuse values such as colors, typography, and sizes, while Classes help you reuse complete groups of styles.

The Design System panel brings them together so you can easily see and manage the styles available across your website.

You don’t need to build a large design system from the beginning. Start with the colors, typography, spacing, and styles you use most often, and expand the system as your website grows.

This keeps your design consistent while making future changes easier to manage.

How Do Elementor v4 Classes Work? A Complete Guide

WPVibes — Tue, 22 Sep 2026 07:18:51 +0000

Styling every button on a website the old way meant setting the same padding, font size, border radius, and hover color on each button, one by one. If you wanted to change how buttons looked later, you had to open every single button and update it by hand. Miss even one, and the site looked inconsistent.

Elementor v4 Classes solve this problem. You set a button's styling once inside a Class, apply that Class to every button on the site, and every button looks the same automatically. Change the Class one time, and every button using it updates everywhere, instantly.

Here's something most tutorials don't explain clearly: in Elementor v4, every single element already has a Class attached to it, whether you set one yourself or not. So you're never really starting from zero. The real question is just which Classes are worth turning into reusable ones, and which ones are fine staying as they are.

This guide covers how Elementor v4 Classes actually work, step by step: how to turn one element's style into something reusable, a simple button pattern you can apply across a whole site, and how to break out of a Class for the rare one-off element that needs to look different.

💡
Notes: If you're on Elementor Pro, we strongly recommend reading the Complete Guide to Elementor v4 Variables first. Classes become significantly more powerful when their property values reference Variables.

What Do You Need Before Working With Classes?

Elementor v4.0 or later. Classes are a v4 feature, so your site needs to be running v4 with the Atomic Editor active. Older, non-atomic elements don't support Classes.
Elementor Free or Pro. Classes work in both versions, so you don't need Pro to follow this article start to finish. Pro users get more out of Classes because they can reference Variables inside a Class's properties. For example, a btn-primary Class can use color-primary as its background, so changing that one Variable updates every button using the Class.
Any WordPress theme. Classes work regardless of which theme is active.
Basic Elementor familiarity. You should already know how to open the editor, add elements, and adjust properties.

What Are Elementor v4 Classes?

A Class in Elementor v4 is a reusable style bundle you can apply to multiple elements. Instead of setting background color, padding, border radius, and hover state on every button one at a time, you define those styles once inside a Class named btn-primary and apply it wherever you need it.

Here's the part most tutorials get wrong: every element in Elementor v4 automatically has a Class.

When you drop a button onto the canvas, Elementor creates a Class named local and attaches it to that button automatically. Every property you set, background, padding, hover state, sits inside that local Class. Nothing is truly inline anymore, the way it used to be in older versions.

This changes how you should think about styling:

Local Classes (shown in pink in the Classes field) apply to one specific element only, and always take priority over any Global Class applied to the same element.
Global Classes (shown in green in the Classes field) apply to every element that uses them.

💡
The workflow: Style locally first, then promote to global once you know you'll reuse it.

How Do You Create Your First Class?

There are actually two ways to create a Class in Elementor v4. The first is faster, the second is better once you already have a styled element you want to reuse.

The quick way: type a new Class name directly

Select any element, open the Classes field in the Style tab, and simply type a new name, for example btn, then press Enter. Elementor creates a brand-new Global Class on the spot (shown in green), ready for you to style. This is the fastest way to start a new reusable Class from scratch.

You'll use this same process when we [structure Classes for a real site]in this guide, so it's worth getting comfortable with it here first.

The reuse way: style locally, then convert to global

Sometimes you style something first and only decide to reuse it afterward. Here's that workflow using a button as the example.

Add and style an element

Drop a button onto the canvas. Notice the Classes field already shows local attached to it, in pink. Style the button:

Padding: 14px 32px
Typography: 16px, weight 600
Border radius: 10px
Background color
Text color
Hover background color

Every property sits inside the local Class right now.

Convert the local Class to global

Once you want to reuse the styling:

Click the three-dot menu next to the local Class name
Select Convert to global class
Rename it to something meaningful, like btn-accent
The Class name turns from pink to green: it's now global

Check out the Video

From this moment on, btn-accent is available site-wide. Apply it to any button and that button inherits the entire styling bundle instantly.

Apply the Global Class to Another Element

Drop a new button anywhere else. In the Classes field, type btn-accent, or select it from the dropdown. The new button matches the styling of the original without you touching a single property.

Now select either button, click on btn-accent inside the Classes field to make it the active Class, and change its padding from 14px to 16px. Every button using btn-accent updates automatically across every page, since you just edited the Class itself, not the individual button.

Check out the Video

How Should You Structure Classes on a Real Site?

Here's a pattern that scales across a production site: the button hierarchy example. Most tutorials show you one Class per element type. Real sites need a bit more structure than that.

Suppose a homepage hero section has two buttons, a primary CTA and a secondary CTA. Most people would create two Classes: btn-primary and btn-secondary. That works, but it duplicates a lot of styling, since both buttons share the same padding, typography, border radius, and hover behavior. Only the colors actually differ.

A better pattern is a layered Class approach.

The btn Class: structural styling

Type btn into the Classes field and press Enter to create it, the same way you created your first Class earlier. This Class will hold every button's shared structure:

Padding: 15px 25px
Typography: 14px, weight 600
Border radius: 20px
Border width: 2px

This Class handles the "button-ness" of every button. Nothing color-related lives here.

Check out the Video

The btn-primary Class: appearance only

Create a second Class the same way, called btn-primary, that only sets appearance:

Background color
Text color
Hover background color

Apply both Classes to a primary button: btn handles structure, btn-primary handles appearance.

Check out the Video

The btn-secondary Class: a different appearance

ame idea. A third Class called btn-secondary that only sets appearance:

Background color (transparent or lighter)
Border color
Text color
Hover appearance

Apply btn and btn-secondary to a secondary button.

Check out the Video

The result: change the shared padding across every button on the site by updating btn once. Change the primary brand color by updating btn-primary once. No duplicated work, no styles quietly drifting apart from each other.

This layered approach, a structural Class plus an appearance Class, is how design systems stay manageable as a site grows past a handful of buttons.

How Do You Override a Class for a One-Off Element?

Sometimes you need a button that follows the same structure and appearance as every other primary button, but needs one thing to look different, say a unique background color for a special CTA on a promotional section. You don't want to create a whole new Class for one element.

Elementor v4's answer: use the local Class every element already has, and let it override just the one property you need to change.

Here's the workflow using the button example:

Apply both btn and btn-primary to the special button, so it inherits all the usual styling: padding, typography, border radius, hover behavior, and the standard primary background color.
In the Classes field, click on local, the class every element already has by default, to make it your active editing target.
Set your custom background color there.

Even though btn-primary already defines a background color for this button, the local Class always takes the highest priority. Setting the background color on local overrides whatever btn-primary says, without touching btn-primary itself or any other button using it.

Check out the Video

You can do this for any property on any element. The rule of thumb: inherit the Class for everything you want consistent, override locally only what needs to be different.

This is how design systems stay maintainable without becoming rigid. You get consistency by default and flexibility when you need it.

What Happens When You Change a Class?

Here's the moment the whole system pays off.

Say you built a homepage with several buttons using the btn and btn-primary combination, spread across the hero section, the services grid, the case study section, the pricing cards, and the final CTA.

Your marketing team decides the primary brand color needs to shift from a dark green to a lighter, brighter green.

Without Classes, that means opening every one of those buttons across the homepage, and every other page they appear on, and manually changing each background color, hover color, and any related border colors.

With the layered Class system, you do this instead:

Select any button that already has btn-primary applied.
In the Classes field, click on btn-primary to make it the active class you're editing.
Change the background color property.
Save.

Every button using btn-primary, across every page of the site, updates instantly.

Check out the Video

Pro users get even more from this: if btn-primary's background references the color-primary Variable instead of a hardcoded hex value, you don't even need to update the Class. Update the Variable once, and both the Class and every button using it change together.

That's the Variables and Classes combination in action.

What's a Good Starter Class Set to Use?

The button hierarchy is one example. Here's a starter set that covers what most business sites actually need, without over-engineering things.

Button

Class Name	Purpose
`btn`	Shared structural styling: padding, typography, border radius, transitions
`btn-primary`	Primary appearance: brand-color background, white text
`btn-secondary`	Secondary appearance: outlined or lighter variant
`btn-accent` (optional)	Attention-grabbing variant using the secondary brand color

Card Classes

Class Name	Purpose
`card`	Base card style: background, padding, border, hover shadow
`card-icon`	Icon wrapper inside cards
`card-featured` (optional)	Highlighted card variant with primary color accent

Section Classes

Class Name	Purpose
`section`	Base section wrapper with standard vertical padding
`section-alt`	Alternate background for tonal variety
`section-dark`	Dark background for final CTAs and testimonials
`section-header`	Centered header block above section content

Layout Classes

Class Name	Purpose
`container`	Content wrapper with max-width and horizontal padding
`grid-3`	Three-column grid for card sections
`grid-4`	Four-column grid for metrics and features

Why this specific set? It covers what a typical business site needs without turning into a maintenance headache. Start here, and add more Classes only when a real, repeating pattern actually demands one. A sprawling Class library is harder to maintain than a small, well-named one.

What Naming Conventions Should You Follow?

Class naming feels trivial on day one and becomes important once you're maintaining a growing library. Three principles that hold up over time:

Name by purpose, not appearance

Good: btn-primary, since it stays correct even if the brand color changes tomorrow
Avoid: btn-blue, since it becomes wrong the day the brand rebrands

Use consistent prefixes

Group related Classes with the same prefix:

Buttons: btn, btn-primary, btn-secondary, btn-accent
Cards: card, card-icon, card-featured
Sections: section, section-alt, section-dark
Grid layouts: grid-2, grid-3, grid-4

Prefixes make Classes easier to find in the Class Manager and reduce naming collisions.

Use hyphen-separated lowercase

Good: btn-primary-outline
Avoid: BtnPrimaryOutline, btn_primary_outline, btnPrimaryOutline

Consistency here matters more than which specific convention you pick. Choose one style and stick with it across every Class.

What Mistakes Should You Avoid With Classes?

A few habits worth avoiding before they cost you time later:

Never promoting local Classes to global. If every element has its own unique local Class, you have zero reusability. Every button, card, and section becomes a one-off. The Class Manager exists specifically to enable reuse. Use it.
Promoting too early. Not every styled element needs to become a global Class. One-off decorative elements can stay local. Promote only once you're confident you'll reuse the styling elsewhere.
Duplicating structure across appearance Classes. If your btn-primary and btn-secondary both include padding, typography, and border radius, you're duplicating work. Split into a shared btn Class for structure, plus appearance-only Classes (btn-primary, btn-secondary). One source of truth for structure, one for each appearance.
Not using the local override option. When you need a one-off variation, don't create a whole new Class for it. Apply the base Class for consistency, then switch just the properties that need to change back to local. This keeps your Class library lean and your special cases flexible.
Not using Variables inside Classes (Pro users). If you're on Pro and hardcoding hex values inside Classes, you're missing the point. A btn-primary Class should reference color-primary, a Variable, as its background, rather than #0F4C81 directly. That way, changing your brand color updates both the Variable and every Class using it.

Frequently Asked Questions

Do Elementor v4 Classes work in Elementor Free?

Yes. Classes are a Free-and-Pro feature. Pro adds the ability to reference Variables inside Class properties, but the core Class system works identically in both versions.

What's the difference between a local and a global Class?

A local Class (pink) applies to one specific element only. A global Class (green) can be applied to any element site-wide, and changing the global Class updates every element using it. Every element starts with a local Class called local . You promote it to global when you want to reuse the styling.

Can I apply multiple Classes to the same element?

Yes. This is exactly how the layered Class pattern works. Apply btn for structure and btn-primary for appearance to the same button. Elementor merges the properties from all applied Classes, with later Classes taking priority when properties conflict.

How do I override a Class for a specific element without creating a new Class?

Apply the Class you want to inherit from, then switch specific properties back to local using the toggle next to the property in the panel. The element inherits everything from the Class except the properties you overrode locally.

Can I convert a global Class back to local?

Yes, but be careful. This breaks the connection between all elements that were using that global Class. They keep the styling but each becomes a separate local Class going forward.

How many Classes should I create for a typical site?

There's no fixed number to hit. A small, well-organized set is usually enough: the starter set in this guide (buttons, cards, sections, and layout) is a good place to start. Add more only when a real, repeating pattern actually demands it.

What happens if I delete a global Class that elements are using?

Those elements revert to their default, unstyled state. Elementor warns you before deletion, but the change is hard to undo. You'd need to reapply the Class or restyle each element by hand.

Wrapping Up

Elementor v4 Classes replace the old "style every element from scratch" workflow with a reusable system. Set up your Classes once, and every new page inherits consistent styling automatically. Update a Class later, and every element using it updates instantly across the entire site.

The takeaways:

Every element already has a Class. You're not creating from scratch, you're deciding scope: local or global.
Local Classes stay unique to one element. Global Classes reuse across the site, and a Local Class always overrides a Global one.
You can create a Global Class two ways: type a new name directly, or style locally first and convert it once you know you'll reuse it.
Layer your Classes. Split structure (btn) from appearance (btn-primary) to avoid duplication.
Use the local override option for one-off variations instead of creating single-use Classes.
Combine Classes with Variables (Pro) for the most powerful, maintainable design system.

Elementor v4 Variables: How to Create and Use Them

WPVibes — Thu, 17 Sep 2026 07:23:50 +0000

When the same color, font, or spacing value is used across multiple pages, changing it manually can take a lot of time. You have to find every place where that value is used and update it individually.

Elementor v4 Variables make this easier. You can define a value once, use it across your site, and update it later from one place. Any element using that Variable updates automatically.

In this guide, you'll learn how Elementor v4 Variables work, how to create your first Variable, and how to use Variables on actual Elementor elements. We'll then build a simple set of color, typography, and spacing Variables that you can reuse throughout your site.

What You Need Before Setting Up Variables

Before following the steps in this guide, make sure you have:

Elementor Pro: Variables require Elementor Pro.
Elementor v4.0 or later: Variables are part of Elementor's v4 design system.
Basic Elementor familiarity: you should know how to open the Elementor editor and select an element.

Elementor v4 uses the Atomic Editor, which is where Variables are available. Existing non-atomic elements can still work alongside the newer v4 features, so you don't need to rebuild an existing site just to start using Variables.

💡
Notes: If your site also runs Contact Form 7, Elementor Forms, Gravity Forms, or Ninja Forms, enable all of them at once. All submissions appear in the same Form Vibes dashboard — no need to switch between plugins.

What Are Elementor v4 Variables?

A Variable is a named value defined once and referenced everywhere. Instead of typing #3B82F6 into 40 different color pickers across a site, create a Variable called color-primary-dark and set its value to #3B82F6. Every element that needs that color references the Variable instead of the hex code.

When the color needs to change, update the Variable value from #3B82F6 to #2563EB. Every element referencing that Variable updates automatically. No hunting, no missed elements, no manual find-and-replace.

Design system professionals call these design tokens. Elementor calls them Variables. Same concept, more approachable name.

Elementor v4 supports three types of Variables:

Colors: hex values used in any color picker (backgrounds, text, borders, shadows)
Typography: font families used in any font-family field
Sizes: numeric values with units, used for spacing, font sizes, borders

This gives you one place to manage commonly reused design values instead of setting them manually on individual elements.

How to Set Up Your First Variables

Let's start by creating a single color Variable and using it on an Elementor element. This will help you understand how the complete Variables workflow works before you create a larger set for your site.

Step 1: Open the Variables Manager

Inside the Elementor editor:
In the top toolbar, click the Design System icon (the droplet-shaped icon on the right).
Clicking this icon opens the Variables Manager, a dedicated panel where every Variable used across your site lives in one place. From here you can create new Variables, rename or edit existing ones, and adjust their values.

Step 2: Create Color Variables

Colors are the most-used Variable type. Start with a six-Variable core set that covers most brand needs:

color-primary-dark: main brand color, buttons, links, accents
color-primary-light: lighter variant for hover states, subtle backgrounds
color-secondary-dark: secondary brand color, complementary accents
color-secondary-light: lighter secondary variant
text-dark: primary text color (usually dark gray, not pure black)
text-light: text color on dark backgrounds (usually white or near-white)

To create each Variable:

Click the + (add) button inside the Variables Manager.
Select Color as the type, since we're creating color Variables in this case, and enter a clear, descriptive Variable name, for example color-primary-dark.
Set the exact hex value using the color picker, either by typing the hex code or dragging the picker to color, click Save. Repeat this same process for all six Variables.

Step 3: Create Typography Variables

Typography Variables let a font family change site-wide from one place. Three Variables cover most needs:

font-heading	font family for all headings (h1 through h6)
font-body	font family for body text and paragraphs
text-base-size	base body font size (usually 16px or 18px)

Create these using the same workflow you just followed for the color Variables. Click the + button inside the Variables Manager, but this time select Typography.
Enter a clear, descriptive name for each Variable. Set the corresponding value (a font family or weight), then click Save.
Repeat this for every Typography Variable you need.

Step 4: Create Size Variables

Size Variables are useful for values that you repeatedly use for spacing or text sizes. Four spacing Variables handle it:

space-section	vertical padding between major sections (80-120px on desktop)
space-block	space between content groups within a section (40-60px)
space-element	space between individual elements (16-24px)
space-small	tight spacing for icon gaps, tag margins (8-12px)

Start creating a Size Variables by selecting the Size as the type from the options shown.
Enter a clear, descriptive name for the Variable, for example spacing-section-lg or radius-card, following the same naming pattern as your other Variables so it stays easy to find later.
Set the value in pixels (or rem, depending on what you're defining), then click Save. Repeat this for each Size Variable you need.

How to Use Variables on Elementor Atomic Elements

Creating Variables is only the first part. Now you need to connect them to the properties of your Elementor elements.

The general process is:

Select an element in the Elementor editor.
Open the property you want to style.
Click the Variables icon next to the property field.
Select the Variable you want to use.

The property will now reference the Variable instead of relying on a manually entered value.

Use a Color Variable on a Button

Suppose you want all your primary buttons to use color-primary-dark.

Select your button and open its background color setting.

Instead of entering a HEX value manually, select: color-primary-dark.

The button background is now connected to that Variable. You can use the same Variable for other primary buttons across your website.

Building a Hero Section with Variables

Here's the demo scenario - a hero section built entirely using Variables:

Property	Variable
Section background	`color-secondary-light`
Main heading text	`text-dark`
Button background	`color-primary-dark`
Button text	`text-light`
Button hover background	`color-primary-light`

Every color decision on that hero section references a Variable instead of a hardcoded hex value. Nothing is inline. Nothing is one-off.

Repeat this pattern for every section on the page. Buttons use color-primary-dark. Headings use text-dark. Section backgrounds alternate between color-bg and color-secondary-light. Nothing is hardcoded.

What Happens When You Change a Variable?

This is where Variables become especially useful.

Open the Variables Manager. Change color-primary-dark from its current hex value to a different color and save.

Every element on the page that references color-primary-dark - the button, the heading accents, the icon colors, the link hover states - updates instantly. No page reloads. No hunting. No missed elements.

Now multiply this across a 20-page site. A brand color change that used to take hours now takes seconds.

That is why Variables matter.

Recommended Starter Variable Set

The Variables used above cover the basics. Here's a fuller starter list for a real site, enough for most business websites without going overboard.

Colors

Variable Name	Purpose
color-primary	Main brand color - buttons, links, primary accents
color-primary-dark	Darker variant - hover states, active states
color-primary-light	Lighter variant - subtle backgrounds, highlights
color-secondary	Secondary brand color - complementary accents
color-text	Main text color - usually dark gray like #1F2937
color-text-light	Secondary text - captions, metadata
color-bg	Page background - usually white or near-white
color-bg-alt	Alternate section background - slight tonal difference
color-border	Borders and dividers - light gray
color-white	Pure white - for text on dark backgrounds

Typography

Variable Name	Purpose
font-heading	Font family for headings
font-body	Font family for body text
text-base-size	Base body font size - 16 or 18px

Spacing

Variable Name	Purpose
space-section	Section vertical padding - 80-120px
space-block	Content group spacing - 40-60px
space-element	Individual element spacing - 16-24px
space-small	Tight spacing - 8-12px

Common Mistakes to Avoid

Five mistakes worth knowing before they cost time:

Naming Variables by appearance instead of purpose. A Variable called blue-primary becomes wrong the moment the brand changes to green. color-primary is always correct regardless of the actual color. Name by function, not appearance.
Creating too many Variables upfront. It's tempting to plan a huge Variable library on day one. Resist. Start with 15-20 Variables, add more only when a real repeating pattern demands them. Fewer, well-named Variables beat 50 half-remembered ones.
Mixing two naming styles. Some people name Variables by purpose, like color-primary. Others name them by value, like blue-600. Both work, but pick one style and stick with it. Mixing the two gets confusing fast.
Forgetting Variables need Pro. The single most common frustration for Free users following v4 tutorials is discovering Variables aren't available in their version. If a project is Free-only, Global Classes work but Variables don't. Plan for this before onboarding a client on Free.
Not using Variables inside Classes. Variables and Global Classes are designed to work together. A button Class should reference color-primary as its background value, not a hardcoded hex. This two-layer system is what makes the v4 design system powerful.

Frequently Asked Questions

Do Variables work in Elementor Free?

No. Variables require Elementor Pro. The free version supports Global Classes but not Variables. This is the most common frustration among Free users trying to follow v4 tutorials.

What happens to my old v3 Global Colors when I migrate to v4?

Your old v3 Global Colors and Fonts keep working as they are. v4 also lets you link your new Variables back to those old colors and fonts, so both can work side by side while you switch over.

How many Variables should I create for a typical site?

Enough to cover your colors, a font or two, and a few spacing sizes, without repeating yourself. The starter list earlier in this guide is a good template. Add more only when you need to.

What's the difference between Elementor Variables and v3 Global Colors?

Both allow you to reuse values, but Variables are part of Elementor v4's broader design system. They are designed to work alongside features such as Global Classes.

Can I rename a Variable after creating it?

Yes. Elementor updates references automatically when a Variable is renamed. There's no orphaning of elements that were using the old name.

Can I use Variables inside custom CSS?

Yes. Elementor outputs Variables as standard CSS custom properties (--e-color-primary-dark, for example). Custom CSS can reference them directly with var(--e-color-primary-dark).

Do Variables work with the free Atomic Editor?

The Atomic Editor is available in Free, but Variables are Pro-only. Free users can build atomic pages with Global Classes; they can't use Variables inside those Classes.

Wrapping Up

Elementor v4 Variables replace the old way of hunting through pages to update one color. Setup takes less time than you'd think, and it pays off more with every page you build.

The takeaways:

Start with a small set of color Variables: primary and secondary colors, each in a light and dark version, plus text colors for light and dark backgrounds
Add font and spacing Variables for a full starter se
Name Variables by what they do, not what they look like
The real value is that one change updates everything
Variables come first. Everything else builds on them

Best Elementor Popup Ideas to Engage Visitors and Increase Conversions

WPVibes — Thu, 10 Sep 2026 06:41:27 +0000

Popups can do much more than collect email addresses. You can use them to promote an offer, answer common questions, highlight free shipping, collect quote requests, re-engage visitors, or show the next step after someone submits a form.

But creating the popup is only one part of the process.

The bigger question is: when should it appear?

A newsletter offer might work well a few seconds after someone lands on your website. A free shipping offer may be more relevant after they reach your products. And a quote form probably shouldn't appear automatically at all.

Elementor Popup Builder gives you several ways to control this. The challenge isn't finding a trigger, it's choosing the one that fits the purpose of your popup and the visitor's current action.

In this guide, we'll look at seven practical Elementor popup examples, the trigger that makes sense for each one, and where you might position the popup so it gets attention without unnecessarily interrupting the visitor.

What You'll Need

Elementor Popup Builder is available with Elementor Pro. This guide assumes you already know how to create and design a basic popup, so we'll focus mainly on choosing the right trigger, position, and setup for each use case.

💡
Notes: If you haven't created a popup before, our complete guide covers that first: Elementor Popup Builder: How to Create Popups That Don't Annoy Visitors.

What Are the Different Ways to Trigger a Popup in Elementor?

Elementor gives you several ways to decide when a popup should appear.

You can automatically show a popup:

after the page has been open for a specified amount of time,
after the visitor scrolls through part of the page,
when they reach a particular element,
after a certain number of clicks,
after they stop interacting with the page, or
when they appear ready to leave.

You can also open a popup after a more specific visitor action, such as clicking a particular button or link, or successfully submitting a form.

The important part isn't simply knowing that these options exist. It's understanding which one fits the popup you're creating.

For example, showing a newsletter offer on Page Load can make sense because it's relevant to most visitors. But a Request a Quote form should usually wait until someone actually asks for a quote.

We'll see both types of situations in the examples below.

What Are All the Elementor Popup Triggers?

Trigger	When the Popup Opens	Often Useful For	Suggested Position
On Page Load	After the page loads and the specified delay passes	Newsletter signup, welcome offer	Center
On Scroll	After the visitor scrolls a specified amount	FAQ, help prompt, secondary CTA	Bottom-right
On Scroll to Element	When the visitor reaches a specific element	Contextual offers, product promotions	Right-middle
On Click	After a specified number of clicks	Engagement-based offers	Depends on the popup
After Inactivity	After the visitor stops interacting for a specified time	Reminder, re-engagement offer	Bottom-left
On Page Exit Intent	When mouse activity suggests the visitor may leave	Last-chance message, re-engagement offer	Center
AdBlock Detection	When the visitor's browser is detected using an ad blocker, within a set number of seconds	Ad-blocker notices, requests to whitelist the site	Center

These positions aren't fixed rules. They are practical starting points based on how much attention the message needs and how much it should interrupt the visitor.

A centered popup demands more attention, while a popup in the corner lets visitors continue viewing most of the page. The right combination depends on what you're showing and how important the message is.

In the examples below, we'll look at different popup scenarios and choose the trigger, opening method, and position that best fit each one.

Before You Choose a Trigger: Conditions, Triggers, and Advanced Rules

There are three Elementor settings you'll regularly see when publishing a popup: Conditions, Triggers, and Advanced Rules.

Conditions: where can the popup appear?

For example, you might make a popup available across your entire site, only on the homepage, or on specific pages.

Triggers: what visitor behavior makes it appear?

This could be Page Load, Scroll, Inactivity, or Exit Intent.

Advanced Rules: are there additional requirements?

For example, you might limit how often the popup appears or show it only after someone has viewed a certain number of pages.

So a popup setup might look like this:

Condition: Homepage.

Trigger: On Page Load after a delay.

Advanced Rule: Limit how often it appears.

With that distinction clear, let's look at some actual popup scenarios.

1. Newsletter Discount Popup: On Page Load

Suppose you're running a clothing store and want to encourage first-time visitors to join your email list.

In return, you're offering 10% off their first order.

Get 10% Off Your First Order

Join our list for new arrivals, offers, and style updates.

[Email Address]

GET 10% OFF

Recommended Setup

Trigger: On Page Load with a delay.
Position: Center.

Why Use On Page Load?

The newsletter offer isn't tied to a particular product or section of the page. It's something that could be relevant to almost any visitor.

That makes On Page Load a good starting point. However, Page Load doesn't mean the popup needs to appear the moment the page opens.

Instead, give visitors a little time to look around: visitor lands on page, browses briefly, newsletter popup appears.

Where Should You Position It?

For this kind of offer, a centered popup works well because the discount is the primary message and requires an action from the visitor.

Keep the design focused. A short headline, one clear benefit, an email field, and a CTA are usually enough.

Set the Trigger in Elementor

Once your popup is ready, click Publish and configure the Display Conditions for the pages where you want it to be available.

Then go to Triggers and enable On Page Load. Set the number of seconds you want Elementor to wait before showing the popup.

You can then use Advanced Rules if you want more control over how frequently the popup appears.

When This Combination Works Well

Page Load with a short delay is worth considering for:

Newsletter signup offers
First-order discounts
Welcome offers
Site-wide promotions

If the message only becomes relevant after someone starts exploring the page, a scroll-based trigger can be more useful.

2. FAQ Help Popup: On Scroll

Visitors browsing an online store often have quick questions about shipping, returns, sizing, or orders. Instead of making them leave the page and search for an FAQ section, you can bring a few common answers directly to them.

For this example, we'll use a chatbot-style FAQ popup that appears after the visitor has scrolled through 50% of the page.

How can we help?

Find quick answers about shipping, returns, sizing, and orders.

EXPAND A QUESTION → GET AN ANSWER → CONTACT US IF YOU NEED MORE HELP

Recommended Setup

Trigger: On Scroll.
Position: Bottom-right.

Why Use On Scroll?

Someone who has just landed on the page probably doesn't need an FAQ prompt yet.

But once they've scrolled through part of the page, they've shown some level of engagement. At that point, offering additional help feels more natural: visitor starts browsing, scrolls through the page, FAQ popup appears.

Why Bottom-right Instead of Center?

The FAQ prompt is useful, but it isn't the main purpose of the page.

Putting it in the bottom-right corner allows the visitor to notice the help option while continuing to see the content behind it.

Configure the Scroll Trigger

Publish the popup and open Triggers. Enable On Scroll.

For someone scrolling down the page, choose the appropriate direction and decide how much of the page they should explore before the popup appears.

The exact scroll amount depends on your page. Test the trigger on the actual page instead of choosing a percentage in isolation.

When This Combination Works Well

On Scroll is useful for FAQ prompts, help options, related content, secondary CTAs, and offers on long pages.

3. Free Shipping Offer: On Scroll to Element

Sometimes a popup is related to a specific section, not a percentage of the page.

Suppose our clothing store homepage has a New Arrivals section. When visitors reach those products, we want to tell them:

Free Shipping on Orders Over $75

Found something you like? Get free shipping when your order reaches $75.

SHOP NEW ARRIVALS

Recommended Setup

Trigger: On Scroll to Element.
Position: Right-middle.

Why Use On Scroll to Element?

When someone reaches New Arrivals, they're actively looking at products. That's a better time to introduce a purchase-related incentive.

Instead of "show the popup after the visitor scrolls 50%," this becomes "show the popup when the visitor reaches the New Arrivals section." The flow: visitor browses homepage, reaches New Arrivals, Free Shipping popup appears.

Why Position It on the Right-middle?

We placed the popup on the right-middle side so the shipping offer remains visible alongside the product section without taking over the entire screen.

Unlike a centered promotional popup, it lets visitors continue looking through the New Arrivals while still noticing the offer.

Set Up the Target Element

Edit the page containing the New Arrivals section and add an identifier under its Advanced settings -> CSS Classes, for example new-arrivals.

Then return to the popup and enable On Scroll to Element. Add the selector for the element you want Elementor to watch.

On Scroll vs. On Scroll to Element

Use On Scroll when the idea is "show this after the visitor has explored enough of the page." Use On Scroll to Element when the idea is "show this when the visitor reaches this specific content." Elementor's own settings documentation confirms these are distinct trigger options.

4. Request a Quote Popup: Open It on a Specific CTA Click

Not every popup needs to appear automatically. Sometimes it should open only when a visitor specifically asks for it.

For this example, we have a Request a Quote button in the Custom Clothing section. When a visitor clicks this button, a quote request form opens on the left side of the page.

Request a Quote

Tell us what you need and we’ll help you find the right option for your order.

Name + Email → Product Type → Quantity + Required Date → Additional Details → REQUEST A QUOTE

Recommended Setup

Opening method: Popup Dynamic Tag
Position: Left or right, depending on the page layout

Why Open It on a Specific CTA Click?

A quote form is useful only for visitors who are interested in placing a custom or bulk order. Showing it automatically while someone is casually browsing would interrupt visitors who may not need it.

Connecting the popup directly to the Request a Quote CTA keeps the interaction intentional.

Why Position It on the Left Side?

We designed the quote form as a larger side popup because it contains several fields and needs more space than a small promotional message.

For this example, we placed it on the left side, leaving part of the original page visible in the background. However, the best side depends on your page layout and where the popup is triggered from.

For example, if the Request a Quote button is on the left side of your layout, you can open the popup from the right. If the button or important content is on the right, opening the popup from the left can work better.

The idea is to position the popup where it covers as little important content as possible, especially the CTA or section the visitor just interacted with.

So instead of treating left or right as a fixed rule, choose the side that works best with your page layout.

Connect the Request a Quote Button to Popup

For this example, you don't need to enable Elementor's regular On Click trigger.

Instead, edit the Request a Quote button and click the Dynamic Tags icon next to its Link field. Select Popup, then open its settings and configure:

Action: Open Popup
Popup: Request a Quote

Now the popup opens specifically when that button is clicked.

💡
Notes: Elementor's built-in On Click trigger and clicking a specific CTA are different. The On Click trigger waits for a configured number of clicks on the page, while the Popup Dynamic Tag lets you connect a particular button or link directly to a popup.

5. Re-engagement Offer: After Inactivity

A visitor who stops interacting with the page hasn't necessarily decided to leave. They may be comparing products, reading something, or simply taking a moment before continuing.

For this example, we'll use a small re-engagement popup that appears after the visitor has been inactive for a while.

STILL BROWSING

Found Something You Like?

Take another look at our latest styles before you go.

CONTINUE SHOPPING →

Recommended Setup

Trigger: After Inactivity
Position: Bottom-left

Why Use After Inactivity?

After Inactivity works well when a visitor hasn't scrolled, clicked, or otherwise interacted with the page for a specified period.

They haven't necessarily decided to leave, so a strong last-chance message may be unnecessary. A small reminder gives them a reason to continue browsing without interrupting the entire page.

Visitor stops interacting → Inactivity timer passes → Re-engagement popup appears

Why Position It at the Bottom-left?

We placed this popup in the bottom-left corner so it acts as a gentle reminder rather than taking over the screen.

The visitor can notice the message and choose to continue shopping while the page they're browsing remains visible.

Configure the After Inactivity Trigger

Open the popup's Triggers settings and enable After Inactivity. Then set how long the visitor should remain inactive before the popup appears.

Choose a delay that gives visitors enough time to browse naturally before the popup appears.

6. New Arrivals Reminder: On Page Exit Intent

Inactivity isn't the only sign that a visitor may need another reason to engage. Sometimes they're actively browsing but then move toward leaving the page.

For this situation, we'll use an Exit Intent popup to give visitors one last opportunity to explore the store's latest products.

BEFORE YOU GO…

Don’t Miss These New Arrivals

One last look? Explore our newest styles before you go.

VIEW NEW ARRIVALS →

Recommended Setup

Trigger: On Page Exit Intent
Position: Center

Why Use Exit Intent?

This popup is meant for someone who appears ready to leave, so the message can be more direct than the inactivity popup.

Instead of showing another generic discount, we're giving the visitor one more opportunity to explore the New Arrivals they may have missed.

Visitor browses the store → Moves toward leaving the page → Exit Intent is detected → New Arrivals popup appears

Why Position It in the Center?

Unlike the subtle inactivity reminder, an exit-intent popup has only a short opportunity to get the visitor's attention.

A centered popup makes the final message more noticeable and gives the CTA a clear focus before the visitor leaves.

Configure the Exit Intent Trigger

Open Triggers and enable On Page Exit Intent.

Once enabled, Elementor can display the popup when the visitor's mouse movement indicates that they may be about to leave the page.

7. Welcome Discount Popup: After Form Submission

Sometimes a popup should appear only after a visitor completes an action.

For this example, our newsletter popup promises 10% off the first order. Instead of showing the discount code before signup, we'll reveal it in a second popup after the visitor successfully submits the form.

YOU’RE IN!

Here’s Your 10% Off

Thanks for signing up! Use this code on your first order.

WELCOME10

START SHOPPING →

Recommended Setup

Opening method: Actions After Submit
Position: Center

Why Show the Popup After Form Submission?

The first popup gives visitors a reason to subscribe, while the second delivers what was promised.

This creates a simple flow:

Get 10% Off Popup → Enter Email → Submit → Welcome Discount Popup → WELCOME10

The discount code isn't shown to everyone who sees the signup form. It appears after the visitor completes the signup.

Why Use a Separate Popup?

You could display a simple success message inside the form, but a separate popup gives the discount code more visibility and provides a clear next step.

In our design, the visitor sees the WELCOME10 code along with a Start Shopping button, so they can immediately return to browsing products.

Why Position It in the Center?

Unlike the FAQ or inactivity popups, this message is the direct result of an action the visitor just completed.

A centered popup works well here because the visitor is already expecting feedback after submitting the form. It also keeps the discount code and next CTA clearly visible.

Open the Popup After the Form Is Submitted

Edit your newsletter form with Elementor. Select the Form widget and go to Content > Actions After Submit. Add Popup.

Then, under the Popup settings, choose Action > Open Popup, and select the Welcome Discount Popup.

Elementor's own documentation covers the exact steps here: Open a Popup When a User Submits a Form.

Test the complete experience: enter email, submit, Welcome Discount popup opens, WELCOME10 is shown.

You Can Close a Popup After Submission Too

If the form itself is already inside a popup and you simply want to dismiss it after a successful submission, choose Action > Close Popup. For example: newsletter popup, submit form, close popup. A similar two-step effect can also be built without Elementor Pro at all, using the free Modal Popup widget from Addon Elements for Elementor, covered in our guide on creating a two-step modal popup.

Other Popup Positions You Can Consider

The examples above use several common popup positions, but you can adjust the placement based on the type of message you're showing.

For example, the bottom-center position can work well for compact, time-sensitive messages such as a countdown timer, limited-time sale, or shipping deadline.

Sale Ends In: 02 : 14 : 36 → SHOP THE SALE

Keeping this type of popup compact lets the message remain noticeable while visitors continue browsing.

Which Elementor Popup Trigger Should You Use?

Instead of asking "which Elementor trigger is best," ask "what should the visitor be doing when this popup becomes useful?"

Popup	Recommended Trigger / Approach	Position	WHY
Newsletter Discount	On Page Load with delay	Center	Introduces the signup offer early without showing it immediately
FAQ Help	On Scroll at 50%	Bottom-right	Makes help available after the visitor has explored part of the page
Free Shipping Offer	On Scroll to Element	Right middle	Shows the shipping incentive when the visitor reaches relevant products
Request a Quote	Specific CTA click	Left	Opens the quote form only when the visitor requests it
Re-engagement	After Inactivity	Bottom left	Gently brings attention back when the visitor stops interacting
New Arrivals Reminder	On Page Exit Intent	Center	Gives visitors one more reason to explore before leaving
Welcome Discount	After Form Submission	Center	Reveals the promised discount after the visitor completes signup

Even similar offers can need completely different timing.

Before signup: "Get 10% Off" triggers On Page Load. After signup: "Here's Your 10% Discount" triggers After Form Submission.

That's why context matters more than the popup type itself.

A Few Things to Keep in Mind When Choosing a Popup Trigger

Don't Interrupt Visitors Earlier Than Necessary

If a popup isn't immediately relevant, wait. An FAQ prompt can wait until the visitor scrolls. A product-related offer can wait until they reach the products. A quote form can wait until they request it.

Match the Position to the Importance of the Message

Use more prominent positions for actions that deserve full attention. Center: signup offers, quote forms, post-submit messages, exit offers. Use less intrusive positions for supporting messages. Side or corner: FAQs, contextual offers, gentle reminders. These are recommendations rather than fixed rules.

Don't Make Visitors See the Same Popup Constantly

Use Advanced Rules where appropriate to control how often a popup is displayed.

Keep the Popup Focused

Keep the message simple, use a clear CTA, and make the popup easy to close. A visitor should understand why the popup appeared and what they're expected to do next without having to read a long explanation.

Frequently Asked Questions

What is the best trigger for an Elementor popup?

There isn't one trigger that's best for every popup. Choose based on when the content becomes useful. Page Load can work for a broad welcome offer, Scroll for secondary prompts, Scroll to Element for contextual offers, and Exit Intent for a last-chance message.

Should I show a popup immediately on Page Load?

Not necessarily. If you're using On Page Load, consider adding a short delay so visitors have time to see the page before the popup appears.

What is the difference between On Scroll and On Scroll to Element?

On Scroll is based on how far the visitor has moved through the page. On Scroll to Element waits until they reach a particular element or section.

How do I open an Elementor popup from a specific button?

For an Elementor element with a Link field, use Dynamic Tags > Actions > Popup, select Open Popup, and choose the popup you want to display.

Is Elementor's On Click trigger the same as opening a popup from a button?

No. Elementor's standard On Click trigger is based on a specified number of clicks. If one specific button or link should open a particular popup, connecting that element directly through the Popup Dynamic Tag or using Open By Selector gives you more precise control.

Can I open an Elementor popup from a navigation menu?

Yes. You can use Open By Selector to connect a matching navigation menu link to a popup.

Can I show a popup after an Elementor form is submitted?

Yes. Add Popup under the Form widget's Actions After Submit, then choose Open Popup and select the popup you want to show. You can also use Close Popup if you want to close the current popup after a successful submission.

Where should I position my Elementor popup?

It depends on the importance of the message. Centered popups work well when you need focused attention, while side and corner positions are generally less intrusive for supporting messages.

Conclusion

Choosing an Elementor popup trigger isn't really about finding the most advanced setting. It's about showing the right message at the moment it becomes useful.

A newsletter offer can appear after a visitor has had a little time to explore. An FAQ prompt can wait until they've started scrolling. A free shipping incentive can appear when they reach your products. A quote form can stay hidden until they request it. And a promised discount can appear only after they successfully subscribe.

So before configuring your next popup, ask what the visitor should be doing when this message becomes relevant, then choose the trigger and position around that moment. That's a much better starting point than simply making every popup appear as soon as possible.

How to Create an Effective Popup Using Elementor Popup Builder

WPVibes — Mon, 07 Sep 2026 06:58:03 +0000

Popups can be useful for collecting email addresses, promoting an offer, sharing an important announcement, or directing visitors to relevant content. But when they appear too quickly, cover the entire screen, or keep showing up repeatedly, they can easily become frustrating.

With Elementor Pro's Popup Builder, you have more control than simply deciding what your popup looks like. You can choose where it appears, when it opens, which pages display it, and the conditions under which visitors see it.

That means you can create popups that support the visitor's experience instead of interrupting it.

In this guide, we'll create a simple newsletter popup in Elementor and configure its display conditions and triggers so that it appears at a more appropriate point in the visitor's journey.

What You'll Need

Elementor's Popup Builder is part of Elementor Pro. It isn't available in the free version of Elementor. You'll also need Elementor Pro active on a WordPress site with at least one page or post to attach the popup to. No coding is required for anything covered here.

Don't have Elementor Pro? The Modal Popup widget from Addon Elements for Elementor is a free way to build a popup, triggered by a button, icon, or image click, using text, images, or saved layouts, without needing Elementor Pro at all.

What Is Elementor Popup Builder?

Elementor's Popup Builder is Elementor's own feature for designing overlay content, including center modals, slide-in banners, and top or bottom bars, directly inside the Elementor editor. It replaces the need for a separate popup plugin for most common use cases, since anything built with standard Elementor widgets can go inside a popup.

Because a popup built this way uses the same widgets, fonts, and colors as the rest of an Elementor site, it tends to look native to the page rather than like an ad wrapped around the content. That changes how a visitor reacts to it before a single trigger or targeting rule comes into play.

How Do You Create a Popup in Elementor?

Let's create the popup first, then we'll configure where and when it should appear.

Step 1: Create a New Popup

Go to Elementor in WP Admin, then navigate to Editor > Templates.
Click Add New Template.
Choose Popup as the template type, enter a name such as Newsletter Popup, and click Create Template.
Elementor will open the template library, where you can choose an existing popup template. For this example, we'll close the template library and build the popup from scratch.

💡
Notes: Already have a popup template? You can import it into Elementor and customize it instead of creating a new popup from scratch.

Step 2: Design Your Popup

Once the Elementor editor opens, add the content you want visitors to see. For our newsletter popup, we'll keep things simple:

Heading: Enjoying this guide?

Description: Get practical WordPress tutorials delivered to your inbox.

Next, add a Form widget, where we will add only an email field and a subscribe button.

Step 3: Adjust the Popup Layout

Next, open the popup settings from the Elementor editor and go to Layout. Adjust the width so that it doesn't occupy too much of the screen.

A width around 380–400px can be a useful starting point on desktop, although the exact value will depend on your content and website design.

The idea isn't to make the popup as large as possible. It only needs enough space for the message and form to remain comfortable to read.

Step 4: Check the Popup on Mobile

Before publishing, switch to Elementor's mobile preview.

A 400px-wide popup that looks small on a desktop monitor can take up most of a phone screen.

Check whether you need to:

Reduce the width or padding
Adjust the heading size
Stack content vertically
Remove unnecessary decorative elements
Increase the close button's clickable area

The goal is the same on every device: keep the popup noticeable without making it difficult to use the page.

Step 5: Publish the Popup

Once you're happy with the design, click Publish.

Before Elementor activates the popup, you'll see Publish Settings. This is where you control where the popup appears and what needs to happen before it opens.

You'll configure three areas: Conditions, Triggers, and Advanced Rules.

Set Conditions to choose where the popup appears. It can be limited to specific pages, specific posts, an entire category, or the whole site, and a popup promoting a specific product makes more sense tied to that product's page than shown site-wide.

A popup shown everywhere to everyone is the version most likely to feel like noise.

Click Next, then set Triggers to choose when the popup appears based on what the visitor does. An on-load trigger with no delay is the single most common reason popups feel annoying, since it fires before a visitor has had any chance to read the page, so a short delay already helps.

A scroll trigger only fires once a visitor reaches a set point on the page. An exit-intent trigger fires when Elementor detects the visitor's cursor moving toward the browser's close or back button, one of the few moments a popup can appear without interrupting anything, since the visitor was already leaving.

A click trigger only opens the popup when the visitor clicks a specific button or link, leaving them fully in control of whether it appears at all.

Click Next, then set Advanced Rules for anything not tied to a direct visitor action, including device type, how many times the visitor has been to the site, and the URL they arrived from. Device rules matter because a popup built for a wide desktop layout can end up covering the entire visible screen on mobile if it isn't restricted for smaller viewports.

Visit-count rules matter because a popup that reappears on every single visit, rather than being limited after a visitor has already seen it, reads as the site not listening.

Once everything is configured, click Save & Close.

💡
Notes: A popup with a visible, easy-to-find close button is not optional. Elementor adds one by default, and it should also be dismissible with the keyboard, not just a mouse click. Removing or hiding the close button, or making a popup impossible to escape without a mouse, is one of the fastest ways to turn a popup into the reason someone leaves a page. See How to Improve Elementor Website Accessibility in WordPress.

Which Triggers Keep a Popup From Feeling Intrusive?

An on-load trigger with no delay is the single most common reason popups get labeled annoying, since it fires before a visitor has had any chance to read the page.

On-load vs. delayed triggers

An on-load trigger fires the moment a page finishes loading. Adding even a short delay changes that first impression, since the popup then appears after the visitor has already started reading rather than instead of letting them start.

Scroll and exit-intent triggers

A scroll trigger fires once a visitor reaches a set point on the page, so it only appears for people already engaged with the content. An exit-intent trigger fires when Elementor detects the visitor's cursor moving toward the browser's close or back button, one of the few moments a popup can appear without interrupting anything, since the visitor was already leaving.

Click-triggered popups

A click trigger only opens the popup when a visitor clicks a specific button or link, putting the visitor fully in control of whether it appears at all. This is the lowest-friction option, and it works well for anything the popup offers as a bonus rather than a requirement.

💡
Tips: If a popup needs different content on every product page rather than one fixed message, that's a genuine dynamic-content situation. Dynific Addons for Elementor pulls ACF field data, including text, images, and repeaters, directly into any Elementor widget, popups included, without custom code. See how it works: How to Display ACF Fields in Elementor Without Elementor Pro

Simple Ways to Make Elementor Popups Less Annoying

Elementor gives you the technical controls, but a few design and content decisions can make just as much difference.

Don't Ask Too Soon

Give visitors a chance to understand what your site offers before asking them to subscribe, download something, or make a purchase.

Scroll, click, and exit-intent triggers can often provide more context than showing every popup immediately on page load.

Keep the Message Short

A popup isn't the place for several paragraphs of copy.

A visitor should quickly understand what you're offering and what they need to do next.

For our example:

Enjoying this guide?

Get practical WordPress tutorials delivered to your inbox.

Subscribe →

That's enough to communicate the offer.

Use One Clear CTA

If the goal is newsletter signup, make subscribing the primary action.

Avoid adding several buttons that compete for attention.

Make Closing Easy

Don't hide the close button or make visitors wait before they're allowed to dismiss the popup.

A popup should offer an opportunity, not trap someone into interacting with it.

💡
Notes: Not every attention-getting element needs to be a popup. A scrolling news ticker can highlight an announcement or offer within the page itself, without covering any content or requiring a visitor to dismiss anything.

Frequently Asked Questions

Does Elementor's Popup Builder require Elementor Pro?

Yes. Elementor's Popup Builder is part of Elementor Pro and isn't available in the free version of Elementor. The free plugin doesn't include a popup creation tool.

What's the best trigger for a popup so it doesn't feel intrusive?

There isn't one universal best trigger, since it depends on the goal. Exit-intent and scroll triggers tend to feel least intrusive because they respond to something the visitor already did, rather than interrupting before they've engaged with the page.

Can I show an Elementor popup only on certain pages?

Yes. Display Conditions let you determine where the popup can appear. You can include or exclude different parts of your website depending on where the popup is relevant.

How do I stop a popup from showing every time a visitor reloads the page?

Elementor's Advanced Rules step, set after Conditions and Triggers when publishing a popup, includes options based on how many times a visitor has been to the site. The exact field names for limiting repeat views should be checked directly in the live Advanced Rules panel, since this needs confirming against the current version of the interface.

Does Elementor's Popup Builder let a popup target specific devices?

Yes. Device targeting is set under Advanced Rules, not under Conditions. Conditions controls which pages or posts a popup is tied to, while Advanced Rules covers device type, visit count, and referrer URL.

Conclusion

Building a popup that visitors tolerate comes down to four decisions: which popup type fits the message, where it's set to appear through Conditions, what triggers it through user action, and what Advanced Rules filter out repeat or mismatched displays. Elementor's Popup Builder walks through all four in sequence every time a popup is published, they just aren't set to the least intrusive option by default.

Before publishing a new popup, preview it on an actual mobile device and confirm the close button works without a mouse. If a scrolling ticker or targeted banner would say the same thing without a popup at all, that's usually the better choice.

Build Custom Gutenberg Blocks Using ACF Blocks (No React Required)

WPVibes — Mon, 31 Aug 2026 08:20:53 +0000

For years, building custom Gutenberg blocks meant learning React, setting up a build pipeline, and wrestling with JavaScript tooling most PHP developers never signed up for. ACF Blocks changes that. If you already know PHP and use Advanced Custom Fields on your projects, you can build production-ready custom Gutenberg blocks today - with the same familiar get_field() calls, no React, no npm, no build step.

This guide walks through building a real plugin with three custom Gutenberg blocks using ACF Blocks, progressing from simple to advanced.

What You'll Build

Three production-ready blocks packaged as a single plugin (wpvibes-acf-blocks):

Testimonial Block: a customer quote with author name, title, and photo
Feature CTA Block: a feature card with image, heading, description, and button link
Team Members Block: a responsive grid of team members using ACF's Repeater field, with configurable column count

Each block lives in its own folder inside the plugin. Adding a new block later means creating one new folder - no changes to any existing file.

Prerequisites

WordPress 6.7 or later (any version supporting ACF Blocks V3)
ACF Pro: required for building custom blocks. The free version of ACF does not support this. ACF Pro is $49/year for a single site.
Local development environment (LocalWP, WordPress Studio, wp-env, or similar)
Any WordPress theme: block themes (Twenty Twenty-Four) or classic themes both work. No child theme required since we're using a plugin.
Basic PHP knowledge: you'll write PHP templates using standard ACF functions.

💡
Notes: This tutorial uses a separate plugin (not a child theme) so the blocks work regardless of which theme is active. This is the difference between our approach and ACF's official tutorial, which uses a child theme.

Step 1: Set Up the Plugin

The plugin contains all three blocks in one folder structure, organized so adding new blocks later is trivial.

1.1 - File structure

Create this folder inside wp-content/plugins/:

wpvibes-acf-blocks/
├── wpvibes-acf-blocks.php
└── blocks/
    ├── testimonial/
    │   ├── block.json
    │   ├── render.php
    │   └── style.css
    ├── feature-cta/
    │   ├── block.json
    │   ├── render.php
    │   └── style.css
    └── team-members/
        ├── block.json
        ├── render.php
        └── style.css

Why this structure?

One block = one folder - every block owns its block.json, render.php, and style.css in the same place. Delete the folder and the block is gone.
Auto-registration - the main plugin file scans blocks/ and registers every folder it finds. Adding a new block never requires touching this file.
Per-block CSS - each block's styles are in its own file, loaded automatically when the block appears on a page.

This is the same pattern used in our PHP-only blocks guide - one block, one folder, self-contained.

1.2 - The main plugin file

Create wpvibes-acf-blocks.php:

<?php
/**
 * Plugin Name: WPVibes ACF Blocks
 * Description: Custom Gutenberg blocks built with Advanced Custom Fields — Testimonial, Feature CTA, and Team Members.
 * Version:     1.0.0
 * Author:      WPVibes
 * Requires at least: 6.7
 * Requires PHP: 7.4
 * Text Domain: wpvibes-acf-blocks
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

/**
 * Register all ACF blocks by scanning the blocks/ folder.
 * Adding a new block later = one new folder, zero changes here.
 */
add_action( 'init', 'wpvibes_acf_register_blocks' );

function wpvibes_acf_register_blocks() {

    // Only run if ACF Pro is active.
    if ( ! function_exists( 'acf_register_block_type' ) ) {
        return;
    }

    $blocks_dir = plugin_dir_path( __FILE__ ) . 'blocks/';

    if ( ! is_dir( $blocks_dir ) ) {
        return;
    }

    // Register every block folder inside blocks/.
    foreach ( glob( $blocks_dir . '*', GLOB_ONLYDIR ) as $block_folder ) {
        register_block_type( $block_folder );
    }
}

What this does in plain words:

The plugin header identifies this folder as a WordPress plugin

wpvibes_acf_register_blocks() runs on WordPress's init hook

ACF Pro check first - if ACF Pro isn't active, the function exits silently (no fatal errors)

glob() finds every folder inside blocks/

register_block_type( $block_folder ) tells WordPress: "there's a block here, read block.json for details"

Once this loop exists, you never touch this file again. Every new block you add as a folder inside blocks/ registers automatically.

Activate the plugin from Plugins → Installed Plugins. Nothing visible yet - we haven't built any blocks.

Step 2: Build the Testimonial Block

The Testimonial block is the simplest of the three. It shows a customer quote with author details and photo. This block introduces the complete ACF Blocks workflow - block.json, field group setup, PHP template, and CSS.

2.1 - Create block.json

Create blocks/testimonial/block.json:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "wpvibes/testimonial",
    "title": "Testimonial",
    "description": "Display a customer testimonial with author details and photo.",
    "category": "text",
    "icon": "format-quote",
    "keywords": ["testimonial", "quote", "review", "author"],
    "supports": {
        "align": ["wide", "full"],
        "anchor": true,
        "jsx": true
    },
    "acf": {
        "mode": "preview",
        "renderTemplate": "render.php"
    },
    "style": "file:./style.css"
}

Line by line, in plain words:

apiVersion: 3 - required for ACF Blocks V3. Always use v3 for new blocks.
name: "wpvibes/testimonial" - the block's unique identifier. Format: {namespace}/{block-slug}.
title, description, category, icon, keywords - how the block appears in the block inserter.
supports.align - allows wide and full-width alignment.
supports.anchor - lets users add an HTML anchor (for jump-to links).
supports.jsx: true - required for ACF Blocks V3.
acf.mode: "preview" - show the rendered block in the editor (not a form view).
acf.renderTemplate - the PHP file that renders the block. Relative to block.json.
style - the stylesheet, loaded automatically in both the editor and frontend.

2.2 - Create the ACF Field Group

The Testimonial block needs four fields. Create them through the ACF admin UI.

Go to wp-admin → ACF → Field Groups → Add New
Field group title: Testimonial Block Fields
Add the following four fields:

Field Label	Field Name	Field Type	Notes
Testimonial Text	testimonial_text	Textarea	Required, Character Limit: 500
Author Name	author_name	Text	Required
Author Title	author_title	Text	Optional, e.g., "CEO, Acme Corp"
Author Image	author_image	Image	Return Format: Image Array, Preview Size: Medium

Scroll down to Settings → Location Rules
Set the rule: Show this field group if → Block → is equal to → Testimonial
Click Publish

💡
Notes: The location rule (Block = Testimonial) is what tells ACF that these fields belong to this specific block. Without this exact rule, get_field() returns null and your block renders empty. This is the single most common mistake when building ACF Blocks. Confirm this rule is set correctly before moving on.

2.3 - Create render.php

Create blocks/testimonial/render.php:

<?php
/**
 * Testimonial block render template.
 *
 * @var array  $block      The block settings and attributes.
 * @var string $content    The block inner HTML (empty for ACF Blocks).
 * @var bool   $is_preview True during backend preview render.
 */

// Get field values.
$testimonial_text = get_field( 'testimonial_text' );
$author_name      = get_field( 'author_name' );
$author_title     = get_field( 'author_title' );
$author_image     = get_field( 'author_image' );

// Build CSS classes — always include the base class + any WordPress-added classes.
$class_name = 'wpvibes-testimonial';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}
if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}

// Support the anchor attribute.
$anchor = ! empty( $block['anchor'] ) ? 'id="' . esc_attr( $block['anchor'] ) . '" ' : '';
?>

<div <?php echo $anchor; ?>class="<?php echo esc_attr( $class_name ); ?>">

    <?php if ( $testimonial_text ) : ?>
        <blockquote class="wpvibes-testimonial__quote">
            <?php echo esc_html( $testimonial_text ); ?>
        </blockquote>
    <?php endif; ?>

    <div class="wpvibes-testimonial__author">

        <?php if ( $author_image ) : ?>
            <img
                class="wpvibes-testimonial__image"
                src="<?php echo esc_url( $author_image['sizes']['thumbnail'] ); ?>"
                alt="<?php echo esc_attr( $author_image['alt'] ); ?>"
                width="60"
                height="60"
            />
        <?php endif; ?>

        <div class="wpvibes-testimonial__info">
            <?php if ( $author_name ) : ?>
                <p class="wpvibes-testimonial__name"><?php echo esc_html( $author_name ); ?></p>
            <?php endif; ?>

            <?php if ( $author_title ) : ?>
                <p class="wpvibes-testimonial__title"><?php echo esc_html( $author_title ); ?></p>
            <?php endif; ?>
        </div>

    </div>

</div>

Key points:

get_field() - ACF's standard function for retrieving field values. Works exactly the same in ACF Blocks as it does anywhere else in ACF.
$block['className'] - WordPress passes any classes the user added via the sidebar's Advanced section.
$block['align'] - the alignment the user picked (wide, full).
$block['anchor'] - the HTML ID the user set.
Every field wrapped in if ( $field ) - optional fields don't render empty tags.
esc_html() and esc_url() - always escape output. Standard WordPress security.

The $author_image array structure (when Return Format is "Image Array"):

$author_image['url'] - full-size URL
$author_image['sizes']['thumbnail'] - thumbnail URL
$author_image['sizes']['medium'] - medium URL
$author_image['alt'] - alt text

2.4 - Create style.css

Create blocks/testimonial/style.css:

.wpvibes-testimonial {
    background: #f9fafb;
    padding: 32px;
    border-radius: 12px;
    max-width: 640px;
    margin: 1.5em auto;
}

.wpvibes-testimonial__quote {
    font-size: 18px;
    line-height: 1.6;
    color: #1f2937;
    font-style: italic;
    margin: 0 0 24px;
    border: none;
}

.wpvibes-testimonial__author {
    display: flex;
    align-items: center;
    gap: 12px;
}

.wpvibes-testimonial__image {
    width: 60px;
    height: 60px;
    border-radius: 50%;
    object-fit: cover;
}

.wpvibes-testimonial__name {
    margin: 0;
    font-weight: 600;
    color: #111827;
}

.wpvibes-testimonial__title {
    margin: 0;
    font-size: 14px;
    color: #6b7280;
}

💡
Notes: The full CSS (with hover states, quote decoration, responsive tweaks) is in the plugin repository at assets/blocks/testimonial/style.css. Copy the complete file into the plugin's blocks/testimonial/ folder before testing.

2.5 - See it working

Create a new page: Pages → Add New
Click + in the block inserter and search for Testimonial
Insert the block
Fill in the fields on the right sidebar:
- Testimonial Text: "WPVibes plugins saved us weeks of development time. The support is fantastic."
- Author Name: Sarah Chen
- Author Title: Lead Developer, TechCorp
- Author Image: upload a headshot
Watch the preview update in real time
Preview the frontend

Your first ACF block is done - no React, no build step, just PHP and CSS you already know.

Step 3: Build the Feature CTA Block

The Feature CTA block introduces two new patterns - the Link field (URL + label + target in one field) and using images at different sizes. Same block structure as Testimonial, just different fields.

3.1 - Create block.json

Create blocks/feature-cta/block.json:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "wpvibes/feature-cta",
    "title": "Feature CTA",
    "description": "A feature card with image, heading, description, and call-to-action button.",
    "category": "design",
    "icon": "megaphone",
    "keywords": ["feature", "cta", "call to action", "card"],
    "supports": {
        "align": ["wide", "full"],
        "anchor": true,
        "jsx": true
    },
    "acf": {
        "mode": "preview",
        "renderTemplate": "render.php"
    },
    "style": "file:./style.css"
}

3.2 - Create the ACF Field Group

Create a new field group called Feature CTA Block Fields with these four fields:

Field Label	Field Name	Field Type	Notes
Feature Image	feature_image	Image	Return Format: Image Array
Heading	heading	Text	Required
Description	description	Textarea	Rows: 3
Button Link	button_link	Link	Return Format: Link Array

Set the location rule: Show this field group if → Block → is equal to → Feature CTA.

💡
Notes: As with the Testimonial block, this Block = Feature CTA location rule is what connects the fields to the block. Missing this rule means get_field() returns null and the block renders empty. Confirm before continuing.

3.3 - Create render.php

Create blocks/feature-cta/render.php:

<?php
/**
 * Feature CTA block render template.
 *
 * @var array $block The block settings and attributes.
 */

$feature_image = get_field( 'feature_image' );
$heading       = get_field( 'heading' );
$description   = get_field( 'description' );
$button_link   = get_field( 'button_link' );

$class_name = 'wpvibes-feature-cta';
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}
if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}

The full render template, with the image and heading markup included, is here: blocks/feature-cta/render.php.

What's new here compared to Testimonial:

The Link field returns an array with three keys: url, title, target. Handle each carefully with the appropriate escape function.
rel="noopener noreferrer" - security best practice when opening links in a new tab. Without this, the new tab can access the original window through window.opener.
Fallback for target - if the user didn't set a target, default to _self.

3.4 - Create style.css

Create blocks/feature-cta/style.css:

.wpvibes-feature-cta {
    display: flex;
    flex-direction: column;
    align-items: center;
    text-align: center;
    gap: 20px;
    padding: 40px 32px;
    background: #ffffff;
    border-radius: 12px;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
    max-width: 400px;
    margin: 1.5em auto;
}

.wpvibes-feature-cta__image {
    width: 80px;
    height: 80px;
}

.wpvibes-feature-cta__image img {
    max-width: 100%;
    max-height: 100%;
    object-fit: contain;
}

💡
Notes: The full CSS (hover effects, transitions, alignment overrides) is in the plugin repository at blocks/feature-cta/style.css.

3.5 - See it working

Insert Feature CTA from the Design category. Upload a small icon-style image, add a heading like "Fast Deployment," a description, and a button label with a URL. Preview the frontend.

Same pattern as Testimonial, more fields, one new field type. The plugin pattern is starting to feel automatic.

Step 4: Build the Team Members Block (with Repeater)

The Team Members block is where ACF Blocks really shines. Using ACF's Repeater field, users add unlimited team members through the sidebar - no coding required. This is the pattern that makes ACF Pro worth the license fee.

The block also introduces a column selector so users pick between 2, 3, or 4 columns.

4.1 - Create block.json

Create blocks/team-members/block.json:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "wpvibes/team-members",
    "title": "Team Members",
    "description": "Display a grid of team members using ACF Repeater fields.",
    "category": "design",
    "icon": "groups",
    "keywords": ["team", "members", "people", "staff"],
    "supports": {
        "align": ["wide", "full"],
        "anchor": true,
        "jsx": true
    },
    "acf": {
        "mode": "preview",
        "renderTemplate": "render.php"
    },
    "style": "file:./style.css"
}

4.2 - Create the ACF Field Group

Create a field group called Team Members Block Fields with these fields:

Block-level fields (things that apply to the whole grid):

Field Label	Field Name	Field Type	Notes
Section Heading	section_heading	Text	Optional
Columns	columns	Text	Enter the number of columns you want
Team Members	team_members	Repeater	Layout: Block. Button Label: "Add Team Member"

Sub-fields inside the team_members repeater:

Sub-field Label	Sub-field Name	Sub-field Type	Notes
Photo	member_image	Image	Return Format: Image Array, Preview Size: Medium
Name	member_name	Text	Required
Role	member_role	Text	Optional
Bio	member_bio	Textarea	Rows: 3, Optional

Set the location rule: Show this field group if → Block → is equal to → Team Members.

💡
Notes: The Block = Team Members location rule connects the fields to this block. Without it, no fields render in the sidebar and have_rows() returns false. Confirm the rule before writing render code.

💡
Tips: When adding the Repeater field, click Add Sub Field inside the repeater to add each column. Sub-fields live INSIDE the repeater, not next to it.

4.3 - Create render.php

Create blocks/team-members/render.php:

<?php
/**
 * Team Members block render template.
 *
 * @var array $block The block settings and attributes.
 */

// Block-level fields.
$section_heading = get_field( 'section_heading' );
$columns         = get_field( 'columns' );
$columns         = $columns ? $columns : 3;

// Build CSS classes.
$class_name = 'wpvibes-team wpvibes-team--cols-' . intval( $columns );
if ( ! empty( $block['className'] ) ) {
    $class_name .= ' ' . $block['className'];
}
if ( ! empty( $block['align'] ) ) {
    $class_name .= ' align' . $block['align'];
}

$anchor = ! empty( $block['anchor'] ) ? 'id="' . esc_attr( $block['anchor'] ) . '" ' : '';
?>

The full render template, with every sub-field's markup included, is here: blocks/team-members/render.php.

Three ACF Pro functions doing the heavy lifting:

have_rows( 'team_members' ) - checks if the repeater has any rows. Similar in shape to WordPress's have_posts().

the_row() - loads the current row's data so get_sub_field() calls work.

get_sub_field( 'field_name' ) - retrieves a sub-field value from the current row.

Once you understand this three-function loop, you can build any repeater-based block - image galleries, feature lists, pricing tiers, timelines, FAQ accordions. The pattern is always the same.

4.4 - Create style.css

Create blocks/team-members/style.css:

.wpvibes-team {
    margin: 2em auto;
}

.wpvibes-team__grid {
    display: grid;
    gap: 32px;
}

.wpvibes-team--cols-2 .wpvibes-team__grid { grid-template-columns: repeat(2, 1fr); }
.wpvibes-team--cols-3 .wpvibes-team__grid { grid-template-columns: repeat(3, 1fr); }
.wpvibes-team--cols-4 .wpvibes-team__grid { grid-template-columns: repeat(4, 1fr); }

.wpvibes-team__member {
    display: flex;
    flex-direction: column;
    align-items: center;
    text-align: center;
    padding: 32px 24px;
    background: #ffffff;
    border-radius: 12px;
    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.08);
}

💡
Notes: The full CSS (with hover effects, responsive breakpoints for mobile, and better typography) is in the plugin repository at blocks/team-members/style.css.

4.5 - See it working

Insert Team Members from the Design category
Set section heading: "Meet Our Team"
Set columns to 3
Click Add Team Member - add several members with photo, name, role, and bio
Watch the grid render in the editor preview
Try changing columns to 2 or 4 to see the layout adapt

Three real, production-ready blocks in one plugin - done.

Get the Full Plugin

The complete plugin - with all three blocks, full CSS, and README - is on GitHub:

To install:

cd wp-content/plugins/
git clone https://github.com/webtechhardik/wpvibes-acf-blocks.git

Then activate from Plugins → Installed Plugins. Adding a new block:

Create a new folder inside blocks/ (e.g., blocks/pricing-table/)
Add block.json, render.php, and style.css to it
Create the matching ACF field group with location rule Block = Pricing Table

That's it. No changes to wpvibes-acf-blocks.php, no manual registration - the loader handles everything.

Why ACF Blocks Makes Block Development Easy

Building custom Gutenberg blocks the "official" way means learning React, setting up a JavaScript build pipeline (Webpack, Babel, Node.js), and mastering the block editor's JavaScript APIs. That's a real learning curve - several weeks of investment before shipping the first block.

ACF Blocks removes almost all of that. If you already know PHP and use ACF on your projects, the entire mental shift is small:

You write PHP templates - the same syntax you've been writing for years
You use get_field() - the same function you already use everywhere else
ACF handles the editor experience - field UI, live preview, validation, all automatic
No build step - save PHP, refresh the browser

The tradeoff is that ACF Pro costs $49/year for a single site. For agencies and freelancers building client sites, that's a rounding error compared to the time saved on every project.

For blocks that need advanced editor experiences (drag-and-drop, deep interactivity, custom media handling), React blocks still make sense. But for the vast majority of custom blocks a WordPress site actually needs - testimonials, feature cards, team grids, pricing tables, hero sections - ACF Blocks does the job faster with less friction.

Frequently Asked Questions

Do I need ACF Pro, or does the free version work?

ACF Pro is required. Custom block registration is a Pro-only feature. The free ACF plugin supports custom fields on posts and pages, but not custom Gutenberg blocks. ACF Pro is $49/year for a single site.

Can I use ACF Blocks in a child theme instead of a plugin?

Yes. The official ACF tutorial uses this approach. The plugin approach shown in this guide is better for portability - the blocks work regardless of which theme is active.

Why does get_field() return null in my ACF Block?

The most common cause is the field group's location rule. It must be set exactly to Block = [Block Name]. If the rule says "Post Type" or anything else, the fields don't attach to the block. This trips up nearly every developer at least once.

Can ACF Blocks use InnerBlocks (nested blocks)?

Yes. Add <InnerBlocks /> to your render.php template. ACF officially supports this in ACF Blocks V3. This gives you container blocks where users can nest core blocks inside.

How do I add a custom icon instead of a Dashicon?

Two ways. Use any Dashicon slug in block.json's icon field (like format-quote or groups). Or, with WordPress 7.1+, register your own SVG icon and reference it. See our Custom SVG Icons guide for the full process.

What's the difference between ACF Blocks and PHP-only blocks (WordPress 7.0+) ?

ACF Blocks require ACF Pro but support 30+ field types (repeater, image, gallery, relationship, etc.). WordPress 7.0's PHP-only blocks are free but limited to 4 attribute types (string, integer, boolean, enum). For simple blocks, PHP-only works. For anything with images, repeaters, or complex data, ACF Blocks wins.

How do I loop through a repeater on the frontend?

Use the standard ACF repeater loop: have_rows(), the_row(), and get_sub_field(). This pattern works exactly the same in an ACF Block as it does anywhere else in ACF. The Team Members block in this guide is a full working example.

Can I ship an ACF field group in the plugin so users don't have to create it manually?

Yes, using ACF's JSON sync feature. Create an acf-json/ folder in the plugin root. When users save a field group, ACF writes it to that folder. Include those JSON files in the plugin zip. When a user activates the plugin, ACF loads the field group automatically. This is the approach ACF's official documentation recommends for shipping fields with plugins or themes.

Wrapping Up

Custom Gutenberg blocks don't require learning React. If you know PHP and use ACF on your projects, you can start shipping real blocks today - with the same familiar workflow you already use for everything else.

The takeaways:

The pattern is consistent - every ACF block is block.json + field group + render.php + style.css in one folder
The location rule is critical - always set the field group to Block = [Block Name], or get_field() returns null
One block = one folder - self-contained, easy to add, easy to remove
Auto-registration scales - the plugin scans blocks/ and registers every folder, so adding a new block requires zero changes to existing files
The Repeater field is the payoff - three functions (have_rows, the_row, get_sub_field) unlock unlimited grid layouts, team lists, pricing tiers, and more

ACF vs Pods: What They Actually Do (and How They're Different)

WPVibes — Thu, 27 Aug 2026 06:40:32 +0000

When you need to add structured custom content to WordPress, two names you’ll often come across are Advanced Custom Fields (ACF) and Pods.

At first, they can look quite similar. Both allow you to add custom fields, create custom post types and taxonomies, build relationships between content, and go beyond the standard WordPress editor.

But they aren't exactly the same.

ACF focuses heavily on custom fields and structured content workflows, while Pods works more like an all-in-one content development framework. Neither one is built to replace the other in every situation, what fits depends on your content structure and which specific capabilities, like repeatable field groups, flexible layouts, or custom database tables, your project actually needs.

Here's a quick look on ACF vs Pods before we get into the details:

	ACF	Pods
Field types (free)	30+	20+ (25+ input types across those field types)
Custom post types, custom fields & taxonomies	Built in, free	Built in, free
Repeating fields	Repeater field groups multiple fields together, PRO only	Individual fields can repeat multiple values; repeating a set of fields together isn't a native option
Options/settings pages	PRO only	Built in, free
Building modular page layouts	Flexible Content field lets you define and reuse layout blocks, PRO only	No equivalent dedicated field for this specific pattern
Multi-image fields	Dedicated Gallery field, PRO only	Free, via the Image field's multiple-upload setting with a gallery display option
Building custom blocks	ACF Blocks (PHP framework), PRO only	Pre-built blocks and a PHP Blocks API for custom blocks, both free
Block Bindings support	PRO only	Free, since Pods 3.2
Data storage	WordPress's standard postmeta table	Postmeta by default, with an option to use dedicated custom database tables
Cost	Free tier plus a paid PRO tier	Free, with optional third-party paid add-ons for niche extras
Support	WordPress.org forums, with ticketed support on PRO	Community Slack and WordPress.org forums

What Is ACF and What Does It Actually Do?

ACF, short for Advanced Custom Fields, lets you add structured custom fields to posts, pages, users, taxonomy terms, and more. Instead of typing everything into WordPress's default editor, you build a field, a text box, an image, a dropdown, and attach it to whatever screen needs it.

Take a team directory as an example. In ACF, you'd create a "Team Members" post type, then build a field group with a Text field for the name, another for the job title, an Image field for the photo, and a Text Area for the bio. Every time someone adds a team member, they see those exact fields laid out cleanly, instead of one open box to fill in however they want.

The free version comes with a wide range of field types and lets you register custom post types and taxonomies right from its own screen, no code needed. ACF is developed by WP Engine, and it's one of the most widely installed plugins in WordPress.

If you want a full, beginner-friendly walkthrough of setting this up, our complete ACF guide covers creating custom post types, taxonomies, and fields step by step.

💡
If your team frequently needs to tweak ACF field values without opening the WordPress admin, use Frontend Editor ACF plugin that adds a lightweight "Edit ACF" button to the frontend admin bar, letting logged-in editors update ACF field data directly on the page they're viewing.

What Is Pods and What Does It Actually Do?

Pods takes a wider view. Instead of just adding fields to content you've already got, it's a framework for building custom content types from the ground up, including ones that can use their own database tables instead of WordPress's usual structure.

Where ACF expects you to already know your content structure and just needs fields attached to it, Pods hands you everything, fields, post types, relationships, in one place. Building that same team directory in Pods means setting up the "Team Members" type and its fields in one continuous flow, rather than treating "the post type" and "the fields" as two separate steps.

Some people find that all-in-one flow faster once they're used to it. Others prefer ACF's more separated setup. Neither is wrong, it just depends what clicks for you.

Pods' free version includes repeatable fields, relationship fields for connecting different content together, and the ability to build custom settings pages, all without a paid tier.

Where Do ACF and Pods Overlap?

Custom Post Types and Taxonomies

This is the most basic thing both plugins need to do, and they both do it the same way now.

Before plugins like these existed, creating something like "Team Members" as its own section in WordPress meant writing PHP code with register_post_type(), or reaching for a separate, single-purpose plugin like CPT UI just to get the admin screen set up. Both ACF and Pods removed that step entirely. Open either plugin's interface, fill in a name, set up a few settings, and "Team Members" appears in your sidebar exactly like Posts or Pages, ready to use.

Taxonomies work the same way. A taxonomy is just a way of grouping entries, the same idea as Categories on a blog, but for your custom content. For a "Team Members" post type, a "Department" taxonomy with options like Marketing, Engineering, or Sales lets you filter and organize team members later, on the frontend or in the admin, without touching a single field.

Pods had this visual setup available earlier in its history, while ACF added its own version in their 6.1 version. At this point, both are equally capable here, no code required either way.

Conditional Logic

Conditional logic just means showing or hiding a field based on what's entered in another field. Both plugins offer this for free, no code required.

Back to the Team Members example: say you only want to collect a "LinkedIn URL" from team members who want their social links shown publicly. You could add a "Show Social Links" toggle, and set the LinkedIn field to only appear once that toggle is checked. Anyone filling in the form who leaves it unchecked never sees the LinkedIn field at all.

Both ACF and Pods handle this the same basic way: pick the field, choose the condition, and the rest happens automatically in the admin screen. It's a small feature, but it keeps forms shorter and less confusing for whoever's entering the content.

Field Types

Field types are just the building blocks you use to collect specific kinds of information. Going back to the "Team Members" fields from earlier, Name and Job Title are Text fields, Photo is an Image field, and Bio is a Text Area. You could also add a Department field as a dropdown, using a Select field tied to the taxonomy above, or a "Currently Hiring" field using a True/False toggle.

Both plugins give you a strong starting set to build all of that: text boxes, number fields, image and file uploads, dropdowns, checkboxes, and relationship fields, which would let you connect a team member to, say, the projects they've worked on.

ACF's free version adds a few specialty fields Pods doesn't include out of the box, like a Google Map field, handy if you wanted to pin each team member's office location, and a Color Picker for grabbing a hex code. Pods covers the same everyday needs with its own set of input types.

Where Do ACF and Pods Genuinely Differ?

Repeating Fields: One Field vs. a Whole Group

Say your team directory needs to support any number of people, not just one. Each person still needs a name, role, photo, and bio. What you actually need is a way to repeat that whole group, once per person, while keeping each person's details bundled together correctly.

ACF PRO's Repeater field does exactly this. You set up the group once, name, role, photo, bio, mark it as a Repeater, and from there your editors just click "Add Row" for each new person. Ten team members means ten clean, bundled entries, each one easy to reorder or edit as a unit.

Pods' free repeatable setting works differently. It repeats a single field, not a group. You can make one field hold multiple values, a list of phone numbers, say, but there's no built-in way to bundle several fields together and repeat the whole set the way ACF PRO does. Try building that same team page with only Pods' free repeatable setting, and you'd end up with separate lists for names, roles, photos, and bios, with nothing guaranteeing that the third name lines up with the third photo.

Building Custom Blocks

WordPress's Block Editor (Gutenberg) lets you build entirely new custom block types, and how much of that is free depends on which plugin you're using.

Pods includes pre-built blocks for free, like a "Pods Field Value" block that lets you drop a field straight into your content with no setup. It also includes its own Blocks API, letting you build entirely custom block types with PHP if the pre-built ones aren't enough, all still free.

ACF's free version doesn't include either of these. Its equivalent, ACF Blocks, a PHP-based framework for building custom block types, requires ACF PRO.

Block Bindings Support

Block Bindings is a separate WordPress feature (added in WordPress 6.5) that connects an existing block, like a Paragraph or Heading, directly to your field data, without building a new block at all.

Pods has supported this for free since Pods 3.2, letting you bind a field's value to a compatible block right from the editor.

ACF's official support for Block Bindings requires ACF PRO. ACF's free version doesn't include this integration.

Where the Data Actually Lives

ACF stores its field data in WordPress's standard postmeta table, the same table WordPress core uses for its own metadata. That keeps ACF closely aligned with how WordPress normally works, which usually means better compatibility with other plugins and fewer surprises when WordPress updates.

Pods offers something different. Its Advanced Content Types can store data in their own dedicated database tables instead of postmeta. Most sites will never notice the difference day to day, it's a behind-the-scenes choice, not something your editors will ever see. It starts to matter at very high content volumes, where standard postmeta queries can slow down and a dedicated table helps.

What It Costs

ACF's core tools, including custom post types and taxonomies, are free. Grouped repeaters, modular layouts, galleries, and settings pages all need ACF PRO, which is an annual license.

Pods gives you equivalent functionality for several of those, for free, with paid options limited to a handful of small, specialized third-party add-ons rather than a full paid tier.

How Do You Decide Which One Fits?

Instead of a verdict, here's a simple way to think it through:

If your content has several related pieces of data that need to repeat together as a set, team members, testimonials with a name and quote and photo, product specs with multiple attributes, that points toward ACF PRO's Repeater, since it's built exactly for that.

If you're building an entirely new content structure from scratch, especially at high volume, a big directory, a large product catalog, Pods' all-in-one setup and optional custom table storage are worth a look.

If budget is the deciding factor and you don't need grouped repetition, Pods' free tier covers a lot of what would otherwise cost you ACF PRO, including settings pages.

If you already know WordPress's admin patterns well and want the field-building experience to feel like "normal WordPress," ACF tends to feel more familiar right away, since it's built to mirror how the rest of the admin already works.

None of this points to one plugin being right for everyone. It's just a starting point for matching the tool to your actual content.

How Do ACF and Pods Work with Elementor?

Both plugins let you pull their field data straight into Elementor, so widgets can show dynamic text, images, and repeated lists instead of hardcoded content. Dynific Addons for Elementor goes further here, with separate integration built for both ACF and Pods, including dedicated widgets for each.

If you want to display ACF fields in Elementor without Elementor Pro, including Repeater, Flexible Content, and Gallery data, Dynific Addons handles that natively. There's also a dynamic testimonial section walkthrough that shows two approaches side by side: a Repeater field for a single page of testimonials, or a custom post type for a library that keeps growing. It's a good real-world look at the repeating-fields decision from earlier, applied to a different example.

💡
Working with Pods instead? Dynific Addons for Elementor also has dedicated Pods field integration, so switching your data layer doesn't mean rebuilding your Elementor workflow.

Frequently Asked Questions

What is the difference between ACF and Pods in WordPress?

ACF focuses on adding custom fields to existing content, with custom post types built in alongside it. Pods is a broader framework for building whole custom content structures, including post types with their own database tables, fields, and relationships, all in one place.

Does Pods have a repeater field like ACF?

Not quite. Pods can repeat a single field to hold multiple values, but it can't group several fields together and repeat that whole set the way ACF PRO's Repeater does.

Is Pods really free compared to ACF?

Yes. Pods' core plugin is entirely free, including features like custom settings pages that require ACF PRO. ACF's basic field-building tools are free too, but grouped repeaters, modular layouts, galleries, and settings pages need its paid PRO tier.

Does ACF or Pods work better with Elementor?

Both work well. Dynific Addons for Elementor supports both with dedicated widgets and dynamic tags, so your choice between them doesn't limit what you can build visually.

Conclusion

ACF and Pods solve overlapping problems from different starting points. One extends existing content with structured fields. The other builds custom content structures from scratch. Neither is inherently better, and the right pick comes down to what your project actually needs, grouped repeating data, dedicated database storage, or just staying free.

Ready to bring either plugin's field data into your Elementor designs? Dynific Addons for Elementor's dynamic content tools work with both, so you're not locked into a workflow you'll have to redo later.

How to Save Contact Form 7 Submissions to Google Sheets

WPVibes — Thu, 20 Aug 2026 12:36:12 +0000

Every Contact Form 7 submission lives in exactly one place: your inbox. If that email lands in spam, or your SMTP setup breaks for a day, that submission is gone. There's no second copy anywhere, because Contact Form 7 was never built to store data at all.

This guide fixes both problems at once. Form Vibes Pro connects Contact Form 7 to Google Sheets automatically, and saves every submission to your WordPress database at the same time. No automation platform, no per-task limits, and no more relying on a single email that might not arrive.

Does Contact Form 7 Save Submissions Anywhere on Its Own?

No. Contact Form 7 sends every submission by email and nothing else. There's no entries table in your WordPress dashboard, no export button, and no built-in backup if that email fails to arrive.

This is intentional. Contact Form 7 was designed to be lightweight, and email-only delivery is part of that design. But it means the only record of a submission is whatever lands in an inbox. A spam filter, a broken SMTP connection, or someone accidentally deleting an email can permanently erase a lead with no way to recover it.

This is exactly the gap Form Vibes closes. Every submission gets saved to your WordPress database the moment it comes in, and from there it can also sync straight to a Google Sheet.

Is Google Sheets Sync a Free or Pro Feature?

Google Sheets sync is a Form Vibes Pro feature. Here's what's relevant to this guide:

Feature	Free	Pro
Save Contact Form 7 entries to WordPress database	Yes	Yes
Export to CSV	Yes (up to 1,000 rows)	Yes (unlimited)
Sync to Google Sheets	No	Yes
Filter which submissions get synced	No	Yes

How to Connect Contact Form 7 to Google Sheets

To keep this concrete, we'll set this up for a simple RSVP form with four fields: your-name, your-email, your-event-date, and your-guest-count. Your own form's field names will be different, but the steps are the same.

Create Your Google API Credentials

Google requires API credentials, so Form Vibes can communicate securely with your Google account. These consist of a Client ID and a Client Secret, generated in Google Cloud Console. The full credential creation process is covered in a dedicated guide. Follow that guide to generate your Client ID and Client Secret, then return here to continue.

Connect Form Vibes to Google Sheets

Go to Form Vibes > Settings > Google Sheet in your WordPress admin. Paste your Client ID and Client Secret into their respective fields. Click Authenticate and sign in with your Google account when prompted. After approving the requested permissions, the connection status updates to show the account as connected.

💡
During authentication, Google shows an "App is not verified" warning. This is expected for a self-configured OAuth connection, and Google's own documentation confirms this is normal for unverified apps. Click Show Advanced, then Go to App, and approve all requested permissions. The connection completes normally.

Set Up the Google Sheets Connection for Your CF7 Form

With your Google account connected, go to Form Vibes > Export Profiles and click Add New. Under Type, select Google Sheet instead of Local Download. This tells Form Vibes to push submissions to a spreadsheet rather than generate a downloadable file.

Choose the Form, Spreadsheet, and Worksheet

On the Data Source tab, select your RSVP form from the Form dropdown. Since Contact Form 7 doesn't have a visual field builder, this dropdown lists the form's admin title, such as "Event RSVP Form," not the individual field tags. Forms appear here once they've received at least one submission.

Choose the Google Spreadsheet where data should be sent. If the spreadsheet you need does not appear, check that the connected Google account has access to it. To create a new spreadsheet directly from Form Vibes, click the plus icon next to the spreadsheet selector.

Select the specific worksheet, or tab, within the spreadsheet. Create a new one using the plus icon if needed.

Then, you will be asked to map the columns to your Google Sheet. Click the "Click here" option to start mapping the columns.

If you want to use custom column headers in the sheet, you can enter the desired names here and map them to the corresponding form fields. For example, you can set the column header Name and map it to the your-name form field.

The Data Filter section lets you sync only the submissions that match specific conditions, instead of sending every submission to Google Sheets. This step is optional. Skip it if you want every RSVP synced.

Map Your Fields on the Columns Mapping Tab

Switch to the Columns Mapping tab. If you want to change the default column mapping or assign a specific form field to a particular spreadsheet column, you can do it here.

After that, map each spreadsheet column to the appropriate Contact Form 7 field. Click Publish to save and activate the connection.

What Happens After Someone Submits Your Contact Form 7 Form?

Once the connection is published, no further action is needed. When a guest submits the RSVP form, Form Vibes saves their name, email, event date, and guest count to your WordPress database, and immediately pushes a new row with those same details to the connected Google Spreadsheet.

The row appears within moments. Anyone with access to the spreadsheet can see the new RSVP without logging into WordPress. Where before this data only existed in an email you might never open, it now lives in two places at once.

Why Aren't Contact Form 7 Submissions Reaching Google Sheets?

The most common cause with Contact Form 7 specifically is a field name mismatch, since CF7 tags are typed by hand rather than picked from a visual list. Beyond that, submissions can also fail to sync because a form isn't yet listed in the dropdown, the connected account can't access the spreadsheet, there's a redirect URI mismatch, or the Google Sheets and Drive APIs aren't enabled. Submit a test RSVP from the frontend first, then check the causes below.

Data is appearing in the wrong columns, or not at all. Open the Export Profile and compare each mapped field against the actual tag names in your Contact Form 7 form editor. A field written as your-eventdate in the form but mapped as your-event-date in Form Vibes will fail silently. Retype the mapping to match exactly.

The Contact Form 7 form is not showing in the Form dropdown. Confirm Contact Form 7 is active. Then confirm the form has received at least one submission on the frontend since Form Vibes was activated. Form Vibes only lists forms that have already received at least one submission.

Spreadsheet is not showing in the dropdown. Check that the Google account connected in Form Vibes Settings has access to the spreadsheet. If the spreadsheet is owned by a different Google account, share it with the connected account before trying again.

Redirect URI mismatch error. The redirect URI entered in your Google Cloud Console app settings must match exactly the one Form Vibes provides. Open your Google Cloud Console project, navigate to OAuth credentials, and verify the redirect URI matches the one shown in Form Vibes Settings.

Google Sheets and Drive APIs are not enabled. Both APIs must be enabled inside your Google Cloud Console project. If sync silently fails and the field mapping checks out, this is usually the cause.

App verification warning during authentication. This is expected for self-configured OAuth apps and does not indicate a problem. Click Show Advanced, then Go to App, and approve all permissions.

Why Form Vibes for Contact Form 7 and Google Sheets?

It starts you from zero, not from a smoother sync. Some plugins improve on a feature Contact Form 7 already has. Contact Form 7 has nothing to improve on here. It has no entries table and no storage of any kind, so Form Vibes is the entire foundation, not an upgrade to one.
Every submission is also saved to your WordPress database. So a temporary Google API hiccup, or a sync that hasn't run yet, never means the data is lost. It's already sitting in WordPress.
One plugin for nine form builders. If you use Contact Form 7 alongside Elementor Forms or WPForms, one Form Vibes install handles all of them. No second connector plugin, no second Google configuration. Setting up Elementor forms with Google Sheets works exactly the same way.
Notes, submission status, analytics, and a role manager included, none of which Contact Form 7 has on its own.

Conclusion

Contact Form 7 was built to be lightweight, and that means it stores nothing on its own. One missed email is the only thing standing between a submission and losing it for good. Form Vibes Pro closes that gap completely: every entry is saved to your WordPress database and synced to Google Sheets automatically, so a single inbox is never the only record you have.

Frequently Asked Questions

Does Contact Form 7 have a built-in Google Sheets integration?

No. Contact Form 7 sends submissions by email only and has no built-in database, export option, or Google Sheets connection. A plugin like Form Vibes Pro is required to sync submissions to a spreadsheet.

Do I need Form Vibes Pro to connect Contact Form 7 to Google Sheets?

Yes. The Google Sheets integration is a Form Vibes Pro feature. The free version still saves every Contact Form 7 submission to your WordPress database and lets you export to CSV on demand. The automatic real-time push to Google Sheets is the Pro upgrade.

What if my Contact Form 7 field names don't match my sheet's column headers?

Nothing will sync correctly until they match. Since Contact Form 7 fields are typed manually rather than chosen from a visual list, open the Export Profile's Columns Mapping tab and compare each field tag against your actual form editor. Fields like your-event-date and your-eventdate look similar but won't map to each other automatically.

Can I sync multiple Contact Form 7 forms to different Google Sheets?

Yes. Set up one Export Profile per Contact Form 7 form, and point each one to its own spreadsheet or its own worksheet inside the same spreadsheet. There's no limit on how many forms you can connect.

Can I filter which Contact Form 7 submissions get sent to Google Sheets?

Yes. The Data Filter section supports Equal, Not Equal, Contain, and Not Contain conditions, and lets you choose whether any or all conditions must match. Filtered-out submissions still get saved to your WordPress database; the filter only affects what reaches Sheets.

Does the same integration work with my other form plugins?

Yes. The Google Sheets sync in Form Vibes Pro works with Elementor Forms, WPForms, Gravity Forms, Ninja Forms, WS Form, Bricks Builder forms, Beaver Builder forms, and Everest Forms, alongside Contact Form 7. One plugin, one Google connection, all your forms.

What's New in WordPress 7.1: Tab Block, Responsive Design, Pseudo States, and much more

WPVibes — Mon, 17 Aug 2026 06:31:09 +0000

WordPress 7.1 comes out on August 19, 2026. It's the second major WordPress release this year. Instead of one headline feature, this release focuses on improving the entire editing experience: responsive design controls, interactive state styling, better media handling, new blocks, editor usability improvements, and a few developer-focused APIs.

Whether you're a site owner, content creator, theme developer, or plugin developer, WordPress 7.1 has something that makes building and managing your site faster and more flexible.

This guide walks through every major feature coming in WordPress 7.1, what it does, and why it matters.

How Does WordPress 7.1 Change the Way You Design Pages?

WordPress 7.1 lets you style how a block looks on different screen sizes and how it reacts to a mouse or keyboard, directly in the editor, without writing a line of CSS. This is the headline feature of the release.

Responsive Styling Comes to the Block Editor

WordPress 7.1 introduces responsive styling directly inside the editor, allowing you to customize how blocks look across different screen sizes without writing CSS.

Depending on the block, you'll be able to configure different values for typography, spacing, layout, dimensions, and other design settings across various screen sizes. This gives much greater control over how your content appears on different devices while keeping the editing experience visual and intuitive.

To use it, select a block, then click the view icon. Choose responsive styling, then pick the device you want to design for: desktop, tablet, or phone. You can make a heading larger on desktop and smaller on mobile, all from the same panel.

💡
Tips: If you're exploring modern WordPress editing capabilities, check out our guide on PHP-only blocks in WordPress 7.0 to see how block development is becoming simpler for developers.

Style Every State Without CSS

Until now, changing how a button or link looks on hover meant writing custom CSS. WordPress 7.1 adds visual controls for these interactive pseudo states, so you can style them directly in the editor.

You can switch between states(Hover, Focus, Focus-Visible, and Active) and set a different color, border, background, shadow, or typography for each one. This makes it easier to build engaging interfaces while also improving accessibility.

A new "State" option lets you set a different style for when someone hovers over a button, tabs into it with a keyboard, or clicks it. The preview updates live as you work.

💡
Notes: Hover and focus control is only available on the Button block and the Navigation Link block.

What's New With the Notes Feature in WordPress 7.1?

Notes in WordPress 7.1 lets you leave feedback on a specific piece of text instead of an entire block, so a comment no longer needs a Slack message to explain which sentence it's about. The feature first appeared in WordPress 6.9, and this release makes it genuinely usable for day-to-day editorial work.

You can now attach a note to a specific selection of text instead of an entire block, so feedback points at exactly the phrase you mean. Notes support rich formatting: bold (Ctrl/⌘ + B), italics (Ctrl/⌘ + I), links (Ctrl/⌘ + K), and emojis, so a note can actually explain itself instead of reading like a plain-text scrap.

Type "@" inside a note and a list of your site's users pops up, letting you tag a specific collaborator, who then gets an email notification linking straight back to the post.

You can also leave more than one note on the same block, which matters if two different people are commenting on two different things in the same paragraph. Long notes collapse by default with a "Show more" toggle, so a detailed note doesn't take over the sidebar.

How Does Client-Side Media Processing Speed Up Your Uploads?

With client-side media processing, WordPress 7.1 moves image processing out of your server and into the browser. Previously, when you uploaded an image, your server had to generate every thumbnail size, handle format conversion, and fix rotation using PHP. Now the browser does that work instead, using a fast, established image library called libvips running right inside your browser, and sends the finished files to WordPress.

The practical upshot: fewer failed uploads on large image files, since you won't hit your host's PHP memory limit mid-upload. Your server also does less work overall, since it's no longer generating every thumbnail size itself. And because the browser's processing produces better-compresse

Two upload types get a real, visible improvement:

Animated GIFs you upload are automatically converted into lightweight video files (using the same kind of technology your browser already uses to play video), so a GIF that used to weigh down your page loads much lighter without you doing anything differently.
HEIC photos, the default format iPhones use, are automatically converted to JPG before upload. You no longer need a plugin just to make iPhone photos work on your site.

Alongside this, the Media Library grid now scrolls infinitely by default instead of paginating, so you can keep scrolling through your library instead of clicking "next page" repeatedly. If you'd rather have the old paginated view back, there's a toggle for it in your user profile settings.

What New Blocks Does WordPress 7.1 Add?

WordPress 7.1 adds two brand new blocks.

Tabs Block

The Tabs block organizes content into clickable panels, letting a visitor click between sections instead of scrolling through a long page. It's a natural fit for FAQs, product comparisons, or any content with a handful of parallel options.

Each tab panel can hold any other block inside it, not just text. You can drop in images, buttons, columns, galleries, or even another Tabs block, so a tab isn't limited to a paragraph.

The tabs themselves are fully styleable. You can set the color, typography, and spacing for the tab buttons, and control the overall look of the tab panel separately, so the whole block can match your site's design.

Playlist Block

The Playlist block lets you embed a simple audio playlist, complete with a waveform visualization that shows the shape of each track. It supports whatever audio file types WordPress already accepts.

The playlist itself has several toggles you can turn on or off: showing the tracklist, artist names, track numbers, track duration, tracklist images, and whether the track image appears on the play button. You can also set the track order to ascending or descending.

Each track has its own settings: artist, album, title, and a track image, so every song in the playlist can show proper metadata and cover art instead of a generic placeholder.

On the styling side, the block has its own controls for the block and the waveform background, and their shape, so the playlist can match your site's design rather than looking like a generic embed.

What's New for the Icon Block in WordPress 7.1?

WordPress 7.1 opens up the Icon block to icon sets beyond WordPress's own defaults, and gives the Icon block itself a few small but useful upgrades.

Custom SVG Icons API

One of the biggest developer-focused additions in WordPress 7.1 is the new Custom SVG Icons API.

Previously, developers who wanted custom icons often had to register them using JavaScript, build custom icon libraries, or depend on third-party solutions. WordPress now provides an official API for registering and managing SVG icon collections.

Developers can register icons individually or as complete collections and make them available throughout the Block Editor. Once registered, these icons can be used in custom blocks, plugins, themes, and the Icon Block itself.

If you build WordPress plugins and want the full technical walkthrough, including a working example plugin, see our complete guide on registering custom SVG icons in WordPress 7.1.

Icon Block Toolbar Improvements

The Icon block itself picked up a few smaller improvements too: newly inserted Icon blocks now start with a default icon instead of an empty placeholder, and the toolbar has new controls to flip an icon horizontally or vertically, or rotate it 90 degrees at a time.

What Else Changed in the WordPress Admin?

A handful of smaller changes add up to a more consistent day-to-day experience.

The admin toolbar now appears inside the post editor and the Site Editor for the first time. Previously, opening either editor made the toolbar disappear entirely, and the only way back to the dashboard was clicking the "W" logo in the editor's own toolbar, which didn't read as a back button to most people.

WordPress 7.1 fixes both problems: the editor toolbar now has a proper back button (a left-pointing chevron), and the admin toolbar itself shows your site's icon.

The Site Editor sidebar finally matches whatever admin color scheme you've chosen in your profile, instead of always defaulting to black regardless of your preference.

There's also a new Identity section under Design in the Site Editor, grouping your site title, tagline, logo, and icon in one place instead of scattering them across Settings and templates.

What Other Small Improvements Should You Know About?

A few smaller design tools rounded out this release. None of these are big enough for their own section, but they're worth knowing about.

Text-shadow support: You can now add a text shadow through Global Styles. It's an early implementation, currently only configurable through theme.json rather than a visual control, so it's more useful to theme developers than to someone editing a single post today.
Background gradients: Several blocks (Group, Accordion, Pullquote, Post Content, and Quote) now support background gradients by default, controllable right in the block settings.
Minimum width: Blocks can now have a minimum width set, alongside the existing height and width controls.

What Developer Experience Improvements Does WordPress 7.1 Bring?

Beyond visual improvements, WordPress 7.1 introduces several enhancements aimed at developers.

Better Block Bindings

Block Bindings already let you connect a block's content, like a Heading, Paragraph, or Button, to a dynamic data source such as a custom field, without writing rendering code. WordPress 7.1 extends that same capability to list items, so a bullet or numbered list can pull from a data source too.

Expanded Abilities API

The Abilities API, which lets WordPress expose specific actions to AI tools and other integrations, picks up better filtering, validation, and a clearer way to mark an ability as publicly available.

If you're building AI-connected features or automations on top of WordPress, this makes those integrations more reliable and easier to control. See our Abilities API + MCP guide for the full guide.

Final Thoughts

WordPress 7.1 is a design and collaboration release: responsive styling and hover states without touching CSS, Notes that finally feel built for teams, faster image handling for supported browsers, and two genuinely useful new blocks. None of it demands a relearning curve, but the responsive and interactive styling controls alone are worth exploring the moment you update.

Keep an eye on your usual update workflow: back up first, test on staging if you run custom blocks or older plugins, then roll it out.

Frequently Asked Questions

When will WordPress 7.1 be released?

WordPress 7.1 is scheduled for release on August 19, 2026. If you're running a production website, it's a good idea to test the update on a staging site first, especially if you use custom themes or plugins.

Does WordPress 7.1 support real-time, multi-person editing?

No. WordPress 7.1 focuses on asynchronous collaboration through the upgraded Notes feature. Two people editing the same post at the same time, Google Docs style, is not part of this release.

What is the Custom SVG Icons API in WordPress 7.1?

The Custom SVG Icons API is a new developer feature that provides a standardized way to register and manage custom SVG icon collections. Developers can register individual icons or entire icon libraries and use them throughout the Block Editor.

Does WordPress 7.1 require a new minimum PHP version?

WordPress 7.1 doesn't introduce a new PHP requirement beyond what WordPress 7.0 already set. If your site runs comfortably on 7.0, it will run on 7.1.

Custom SVG Icons: An Exciting WordPress 7.1 Feature

WPVibes — Thu, 13 Aug 2026 06:35:51 +0000

For years, adding a custom icon to the block editor meant reaching for JavaScript, a build step, or a workaround that only half-worked. WordPress 7.1 is about to change that.

A new public API for custom SVG icons is landing in the next release. You'll be able to register your own icons, group them into named collections, and have them show up in the core/icon block picker, render server-side in PHP, and appear over the REST API, all from a plugin, with no JavaScript build step at all.

This guide walks through building a small plugin called wpvibes-custom-icons that registers a collection, adds icons two different ways (inline SVG and file paths), and shows how to use those icons in the block editor, in PHP templates, and as custom block icons. The complete plugin is on GitHub.

WordPress 7.1 releases on August 19, 2026. The code below matches what's expected to ship on release day, and we'll come back and verify every detail against the final build once it's out.

What You'll Build

A wpvibes-custom-icons plugin with a registered icon collection called wpvibes
Three ready-to-use icons: a heart (registered inline), a star, and a bookmark (both registered from .svg files)
A bulk registration pattern that reads every SVG file from a folder and registers each one automatically
A practical shortcode for inserting any registered icon into post content
Real integration with our PHP-only blocks guide, using a custom icon as a block icon

Prerequisites

WordPress 7.1 or later (7.1 RC works for development)
A few SVG icon files (or use the ones provided below)
Local development environment (LocalWP, WordPress Studio, wp-env)
Basic PHP knowledge

Step 1: Understand the API in Three Minutes

WordPress 7.1's custom icons API has three main functions and one organizing concept.

The functions:

wp_register_icon_collection( $name, $args ): register a named group of icons
wp_register_icon( $name, $args ): register a single icon
wp_get_icon( $name, $args ): render an icon's SVG in PHP (returns the SVG string)

The organizing concept: collections. Every icon belongs to a collection. The collection name becomes a prefix for every icon inside it, which is what makes core/plus different from wpvibes/plus. This keeps custom icons from colliding with core icons or with other plugins.

Two ways to provide the SVG when registering:

content: the SVG markup as a string, embedded directly in PHP
file_path: an absolute path to an .svg file on disk

Use one or the other per icon, not both. Inline content is handy for one or two icons; file_path scales better for a folder of many.

That's the API. Now let's build with it.

Step 2: Set Up the Plugin and Register the Collection

While building this, one thing became clear quickly: the collection has to be registered before you can add icons to it. If you try to register an icon whose collection doesn't exist yet, the icon silently fails to appear in the picker.

Create a folder inside wp-content/plugins/:

wpvibes-custom-icons/
├── wpvibes-custom-icons.php
└── icons/
    ├── star.svg
    └── bookmark.svg

Create wpvibes-custom-icons.php with the plugin header and the collection registration:

<?php
/**
 * Plugin Name: WPVibes Custom Icons
 * Description: Register custom SVG icons for WordPress 7.1+.
 * Version:     1.0.0
 * Author:      WPVibes
 * Requires at least: 7.1
 * Requires PHP: 7.4
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

define( 'WPVIBES_ICONS_PATH', plugin_dir_path( __FILE__ ) );

/**
 * Step 1: Register the icon collection.
 */
add_action( 'init', 'wpvibes_register_icon_collection' );

function wpvibes_register_icon_collection() {

    wp_register_icon_collection(
        'wpvibes',
        array(
            'label' => __( 'WPVibes', 'wpvibes-icons' ),
        )
    );
}

The collection name (wpvibes) becomes the prefix for every icon that follows: wpvibes/heart, wpvibes/star, and so on. The label is what shows up as a section heading in the icon picker.

Activate the plugin from Plugins → Installed Plugins. Nothing to see yet, since collections don't render until they contain icons.

Step 3: Register Icons Two Ways

WordPress supports two ways to register an icon. This step uses both: the inline content method for the heart icon, and the file_path method for star and bookmark.

3.1: Register an inline icon with content

The heart SVG lives directly in the PHP file. Useful when there's just one or two icons and you don't want extra files.

Add this to wpvibes-custom-icons.php:

/**
 * Step 2: Register icons using inline SVG content.
 */
add_action( 'init', 'wpvibes_register_inline_icons', 20 );

function wpvibes_register_inline_icons() {

    wp_register_icon(
        'wpvibes/heart',
        array(
            'label'   => __( 'Heart', 'wpvibes-icons' ),
            'content' => '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M20.84 4.61a5.5 5.5 0 0 0-7.78 0L12 5.67l-1.06-1.06a5.5 5.5 0 0 0-7.78 7.78l1.06 1.06L12 21.23l7.78-7.78 1.06-1.06a5.5 5.5 0 0 0 0-7.78z"/></svg>',
        )
    );
}

How the code flows:

The action hooks into init at priority 20, which is later than the collection registration (default priority 10), so the collection exists before the icon tries to join it.
The icon name wpvibes/heart follows the pattern collection/icon-slug.
The label shows in the icon picker; content holds the SVG markup.
The SVG uses stroke="currentColor" so the icon inherits color from surrounding text, with no hardcoded fill.

3.2: Register icons from `.svg` files

For icons stored on disk, use file_path instead. Save these two files in the icons/ folder:

icons/star.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
</svg>

icons/bookmark.svg:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <path d="M19 21l-7-5-7 5V5a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2z"/>
</svg>

Now register both from PHP:

/**
 * Step 3: Register icons from .svg files.
 */
add_action( 'init', 'wpvibes_register_file_icons', 20 );

function wpvibes_register_file_icons() {

    wp_register_icon(
        'wpvibes/star',
        array(
            'label'     => __( 'Star', 'wpvibes-icons' ),
            'file_path' => WPVIBES_ICONS_PATH . 'icons/star.svg',
        )
    );

    wp_register_icon(
        'wpvibes/bookmark',
        array(
            'label'     => __( 'Bookmark', 'wpvibes-icons' ),
            'file_path' => WPVIBES_ICONS_PATH . 'icons/bookmark.svg',
        )
    );
}

Same registration function, same collection. Only content becomes file_path. WordPress reads the file on demand.

Now open the core/icon block in the editor. The picker shows a new WPVibes section with Heart, Star, and Bookmark. Insert any of them.

💡
Notes: If an icon doesn't appear, the most common cause is registering the icon before the collection exists. Make sure the collection is registered first (default priority), and the icons are registered after (priority 20 in the examples above).

Step 4: Register a Whole Folder of Icons (Bulk Pattern)

For a real icon library, registering one icon at a time doesn't scale. Nobody writes 30 wp_register_icon() calls by hand. The practical pattern: drop SVGs into a folder, and let PHP auto-register everything on the next request.

Replace the individual wpvibes_register_file_icons() function with this bulk version:

add_action( 'init', 'wpvibes_register_all_file_icons', 20 );

function wpvibes_register_all_file_icons() {

    $icons_dir = WPVIBES_ICONS_PATH . 'icons/';
    $svg_files = glob( $icons_dir . '*.svg' );

    if ( empty( $svg_files ) ) {
        return;
    }

    foreach ( $svg_files as $file_path ) {

        $slug  = basename( $file_path, '.svg' );
        $label = ucwords( str_replace( '-', ' ', $slug ) );

        wp_register_icon(
            'wpvibes/' . $slug,
            array(
                'label'     => $label,
                'file_path' => $file_path,
            )
        );
    }
}

Code flow in plain words:

glob( $icons_dir . '*.svg' ) returns every .svg file in the folder.
basename( $file_path, '.svg' ) takes just the filename without extension, so advanced-button.svg becomes advanced-button.
ucwords( str_replace( '-', ' ', $slug ) ) turns the slug into a readable label: advanced-button becomes "Advanced Button" for the picker.
The loop registers each icon under the wpvibes/ collection.

Drop any new SVG into the icons/ folder, refresh the editor, and it appears in the picker. No code changes needed.

This is the pattern used to register the WPVibes icon library. The same six lines register the entire icon set: heart (registered inline earlier), star, bookmark, and any additional icons dropped into the folder.

Step 5: Use the Icons in Three Places

Once icons are registered, three places automatically get access to them. Here's each one with a small example.

5.1: In the core/icon block

The core/icon block picker automatically shows every registered collection. Users insert the block, pick a WPVibes icon, and it renders on the frontend. No extra code needed.

Icons also appear at the REST endpoint /wp-json/wp/v2/icons (with a companion /wp-json/wp/v2/icon-collections endpoint for collections), for any external tool that reads WordPress data.

5.2: In PHP via wp_get_icon()

The wp_get_icon() function returns an icon's SVG as a string. The simplest form:

echo wp_get_icon( 'wpvibes/heart' );

For real templates, pass a second argument to control size, class, and accessibility:

echo wp_get_icon(
    'wpvibes/star',
    array(
        'size'  => 32,
        'class' => 'featured-icon',
        'label' => __( 'Featured', 'wpvibes-icons' ),
    )
);

size sets the SVG's width and height in pixels
class adds a CSS class to the SVG element
label sets aria-label for screen readers

A practical shortcode example. Here's a small [wpvibes_icon] shortcode that lets anyone drop an icon into post content:

add_shortcode( 'wpvibes_icon', 'wpvibes_icon_shortcode' );

function wpvibes_icon_shortcode( $atts ) {

    $atts = shortcode_atts(
        array(
            'name'  => 'heart',
            'text'  => '',
            'size'  => 24,
            'class' => '',
        ),
        $atts
    );

    $icon = wp_get_icon(
        'wpvibes/' . sanitize_key( $atts['name'] ),
        array(
            'size'  => absint( $atts['size'] ),
            'class' => sanitize_html_class( $atts['class'] ),
        )
    );

    if ( ! $icon ) {
        return '';
    }

    return sprintf(
        '<span class="wpvibes-icon-inline">%s %s</span>',
        $icon,
        esc_html( $atts['text'] )
    );
}

Use it inside any post, page, or widget:

[wpvibes_icon name="heart" text="Hello World"]

[wpvibes_icon name="star" text="Featured post" size="32"]

[wpvibes_icon name="bookmark" text="Save for later" size="20"]

The icon appears next to the text, sized to whatever the size attribute says. Because the SVG uses currentColor, the icon picks up the surrounding text color automatically.

5.3: As a custom block icon in register_block_type()

Custom icons can replace the default Dashicon in any block registration. In our PHP-only blocks guide, block icons look like this:

'icon' => 'warning',   // Uses a Dashicon

With WordPress 7.1 custom icons, that becomes:

'icon' => 'wpvibes/star',   // Uses a registered custom icon

The block inserter now shows the branded WPVibes icon instead of a generic Dashicon. This works for both JavaScript-registered blocks and PHP-only blocks.

Same registration function, three consumer contexts. This "register once, use everywhere" pattern is the same architecture used by WordPress's Abilities API, a good sign that WordPress is heading toward a genuinely consistent developer story across its foundational APIs.

Step 6: Style Custom Icons with CSS

Custom icons look native by default, but real integration means they adapt to their surroundings: inheriting text color, scaling with font size, changing appearance on hover.

The class argument passed through wp_get_icon() (shown in Step 5.2) already covers the standard case of adding a CSS hook to the SVG. This section covers what to do with that hook, plus patterns that work everywhere the icon appears, including in the block editor where the class argument isn't in play.

6.1: Use currentColor for color inheritance

The single most important pattern in SVG design: use stroke="currentColor" (or fill="currentColor") instead of hardcoded colors.

<!-- ❌ Hardcoded color: icon always red -->
<svg viewBox="0 0 24 24" 
stroke="#dc2626" 
stroke-width="2">    

<path d="..."/></svg>

With currentColor, an icon inside red text renders red. Inside a dark theme, it renders dark. Inside a link, it matches the link color. The SVG behaves like text.

This is why the icons in our library ship without hardcoded colors. It's the difference between an icon that fits any theme and one that clashes with half of them.

6.2: Override color when a specific color is needed

Sometimes an icon must be a specific color regardless of surroundings, like a brand mark or a status indicator. Use CSS to force it:

.featured-icon {
    color: #f59e0b;   /* Amber, regardless of surrounding text */
}

Because the SVG uses currentColor, setting color on the SVG (via the class from Step 5.2) cascades into its stroke or fill. The icon renders amber even inside dark text.

6.3: Size and hover states

For icons rendered through the shortcode or wp_get_icon(), the size argument handles pixel sizing directly. For CSS-controlled sizing or hover states:

.wpvibes-icon-inline svg {
    transition: transform 0.15s ease-in-out;
}

.wpvibes-icon-inline:hover svg {
    transform: scale(1.1);
}

6.4: When to use CSS classes vs. the `size` argument

Use size in wp_get_icon() for one-off cases where the exact pixel size matters and there's no reason to write CSS.
Use CSS classes (via the class argument, or on the wrapper element) when the icon appears in many places and should stay consistent, or when styling depends on state (hover, focus, active) or context (inside a link, inside a heading).

For the shortcode example in Step 5.2, both approaches work. Small tweaks per shortcode use the size attribute; site-wide consistency uses CSS on .wpvibes-icon-inline svg.

Step 7: Remove Icons and Collections

WordPress 7.1 ships two matching functions for unregistering: one for a single icon, one for a whole collection.

7.1: Remove a single icon

Useful during development, or when a plugin update drops an icon:

wp_unregister_icon( 'wpvibes/bookmark' );

The icon disappears from the picker on the next request. Any post that already inserted this icon in a core/icon block will render empty (WordPress doesn't rewrite post content).

7.2: Remove the entire collection on deactivation

When the plugin is deactivated, all its icons should stop appearing in the picker. Unregistering the collection removes every icon inside it in one call:

register_deactivation_hook( __FILE__, 'wpvibes_unregister_icons' );

function wpvibes_unregister_icons() {

    wp_unregister_icon_collection( 'wpvibes' );
}

No need to loop through individual icons. The collection cleanup handles it all.

Get the Full Plugin

The complete wpvibes-custom-icons plugin, with sample SVGs, README, and the full bulk registration pattern, is on GitHub.

How Custom Icons Fit the Bigger Picture

WordPress 7.1's custom icons follow the same architectural pattern as the Abilities API and the PHP-only blocks guide covered earlier: register once, use everywhere. The core/icon block reads from the registry, wp_get_icon() reads from the same registry in PHP, and the REST API exposes it to external tools including AI agents.

WordPress is deliberately building foundational APIs, abilities, icons, block bindings, that follow the same register-once, discoverable-everywhere pattern. Plugin authors who invest in these APIs get their code integrated into the editor, the REST layer, and any tool built on the WordPress data model. Icons look like a small feature on the surface. Underneath, they're another piece of a much bigger shift in how WordPress plugins get built.

Wrapping Up

This is a small API on paper, but it quietly closes a gap plugin developers have worked around for years. Register a collection, add icons inline or from files, and use them across the block editor, PHP templates, and REST, all without touching JavaScript. The bulk pattern with glob() scales from three icons to three hundred without changing the code.

The takeaways:

Collections come first: icons attach to collections, not the other way around
Two registration methods: content for inline, file_path for icons on disk. Both work in the same collection.
Bulk registration beats per-icon calls: glob() over a folder registers unlimited icons in six lines
wp_get_icon( $name, $args ) accepts size, class, and label: a proper templating function, not just an SVG dump
currentColor in SVGs is the pattern to follow: icons that adapt to their surroundings look native everywhere
The same registration serves editor + PHP + REST: one function call, three consumer contexts

Custom icons complete the story for custom blocks. Combined with the PHP-only blocks guide, a plugin can now register blocks, register their icons, and ship a completely branded editor experience without a build step. Once WordPress 7.1 ships on August 19, this is genuinely one of the releases worth updating for.

Frequently Asked Questions

Do I have to register a collection before registering icons?

Yes. Icons must belong to an existing collection, or they silently fail to appear in the picker. Register the collection at default priority on init, then register icons at a higher priority (like 20) so they run after.

Can I mix inline content icons and file_path icons in the same collection?

Yes. Each wp_register_icon() call is independent. Use content for one or two icons, file_path for the rest. WordPress treats them the same once registered.

Do custom icons work as block icons in register_block_type()?

Yes. Pass the registered icon name (like 'wpvibes/star') to the icon key in register_block_type(). The block inserter shows the custom SVG instead of a Dashicon. Works for JavaScript-registered blocks and PHP-only blocks.

Does wp_get_icon() return the icon as HTML, or as a string?

wp_get_icon() returns the SVG as a string, so you can echo it directly or wrap it in your own HTML. The second $args array accepts size, class, label (for aria-label), and title.

What SVG attributes should I remove before registering an icon?

Remove hardcoded fill and stroke colors, width and height attributes on the root <svg> (leave the viewBox), and any <style> blocks or scripts. Keep viewBox and structural attributes. Use currentColor for any color reference.

Can I register icons from a theme instead of a plugin?

Yes. The same wp_register_icon() call works from a theme's functions.php using get_stylesheet_directory() for the file path. The trade-off is that icons registered from a theme disappear when the theme changes.

What happens if two collections have the same icon name?

Collections namespace icon names, so wpvibes/heart and myplugin/heart coexist without conflict. The full name including the collection prefix is what makes each unique.

Does WordPress sanitize SVGs on registration?

WordPress does not modify the SVG content on registration. The exact string you provide (or file contents you reference) is what gets served. Sanitize SVGs yourself before shipping: remove scripts, external references, and anything unnecessary.

PHP-Only Blocks in WordPress 7.0: The Developer's Complete Guide

WPVibes — Thu, 06 Aug 2026 06:05:10 +0000

For the first time in eight years, you can register real Gutenberg blocks using only PHP - no React, no npm, no Webpack, no build step. Just a plugin file, register_block_type(), and a new autoRegister flag introduced in WordPress 7.0.

This guide walks you through building a complete plugin with two production-ready blocks - a Notice block and a Category Display block - from setup to shipping. The complete plugin, including all CSS and helper files, is on GitHub. Everything you need to follow along is in this article; everything you need to ship is in the repository.

A quick clarification before we start: Server-rendered Gutenberg blocks have existed for years, but until now they always required a JavaScript layer using ServerSideRender to scaffold the block in the editor - even though the actual rendering happened in PHP. You still needed block.json, an edit.js file, and a build step. WordPress 7.0's autoRegister => true flag removes that JavaScript ceremony entirely.

We'll cover architecture and comparisons at the end. First, let's build.

Who Is This Guide For?

WordPress developers comfortable with PHP who want to build blocks without a JavaScript build pipeline. Basic knowledge of register_block_type() helps but isn't required - this guide explains each step.

What Will You Build?

Notice Block: Title, description, and four skin variants (Alert, Warning, Success, Info)
Category Display Block: Show post categories in Grid, List, or Compact layout, with optional images (via ACF if installed, plugin placeholder if not), post counts, and recent post lists

Prerequisites

WordPress 7.0 or later
Local development environment (LocalWP, WordPress Studio, wp-env, or similar)
Code editor
Basic PHP knowledge
Optional: Advanced Custom Fields - the Category Display block supports ACF images if available and falls back to a placeholder otherwise

💡
Tips: Test all changes on a local or staging site first. WordPress 7.0 is recent and PHP-only blocks are a new API - verify everything before shipping to production.

Step 1: Set Up the Plugin

The plugin contains both blocks, organized cleanly so more blocks can be added later without refactoring.

1.1 - File structure

Create this folder inside wp-content/plugins/:

wpvibes-blocks/
├── wpvibes-blocks.php
├── includes/
│   └── class-blocks-loader.php
├── blocks/
│   ├── class-notice-block.php
│   └── class-category-display-block.php
└── assets/
    ├── notice.css
    ├── category-display.css
    └── images/
        └── category-placeholder.png

Why this structure?

The main plugin file loads everything. The loader class registers all blocks in one loop. Each block lives in its own file. Each block's CSS lives in its own file too. Adding a new block later means creating one new class file, adding one line to the loader, and registering one stylesheet. This pattern scales - a plugin with 20 blocks stays maintainable; a single 5,000-line file does not.

1.2 - The main plugin file

Create wpvibes-blocks.php:

<?php
/**
 * Plugin Name: WPVibes Blocks
 * Description: PHP-only Gutenberg blocks — Notice and Category Display.
 * Version:     1.0.0
 * Author:      WPVibes
 * Requires at least: 7.0
 * Requires PHP: 7.4
 */

if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

define( 'WPVIBES_BLOCKS_VERSION', '1.0.0' );
define( 'WPVIBES_BLOCKS_PATH', plugin_dir_path( __FILE__ ) );
define( 'WPVIBES_BLOCKS_URL', plugin_dir_url( __FILE__ ) );

require_once WPVIBES_BLOCKS_PATH . 'blocks/class-notice-block.php';
require_once WPVIBES_BLOCKS_PATH . 'blocks/class-category-display-block.php';

require_once WPVIBES_BLOCKS_PATH . 'includes/class-blocks-loader.php';
WPVibes_Blocks_Loader::init();

The main file wires things together. Nothing more.

1.3 - The loader

Create includes/class-blocks-loader.php:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class WPVibes_Blocks_Loader {

    private static $block_classes = array(
        'WPVibes_Notice_Block',
        'WPVibes_Category_Display_Block',
    );

    public static function init() {

        add_action( 'init', array( __CLASS__, 'register_styles' ), 5 );
        add_action( 'init', array( __CLASS__, 'register_all_blocks' ), 10 );
    }

    public static function register_styles() {

        wp_register_style(
            'wpvibes-notice',
            WPVIBES_BLOCKS_URL . 'assets/notice.css',
            array(),
            WPVIBES_BLOCKS_VERSION
        );

        wp_register_style(
            'wpvibes-category-display',
            WPVIBES_BLOCKS_URL . 'assets/category-display.css',
            array(),
            WPVIBES_BLOCKS_VERSION
        );
    }

    public static function register_all_blocks() {

        foreach ( self::$block_classes as $class_name ) {

            if ( ! class_exists( $class_name ) ) {
                continue;
            }

            $block = new $class_name();
            $block->register();
        }
    }
}

Activate the plugin from Plugins → Installed Plugins. Nothing visible yet - the blocks come next.

Step 2: Build the Notice Block

The Notice block shows a message with a title, description, and one of four skin options (Alert, Warning, Success, Info). It's the simpler of the two blocks - a good starting point for learning the API.

2.1 - Create the block class

Create blocks/class-notice-block.php:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class WPVibes_Notice_Block {

    public function register() {

        register_block_type(
            'wpvibes/notice',
            array(
                'title'           => __( 'Notice', 'wpvibes-blocks' ),
                'description'     => __( 'A notice or callout with 4 skins.', 'wpvibes-blocks' ),
                'category'        => 'text',
                'icon'            => 'warning',
                'style'           => 'wpvibes-notice',
                'editor_style'    => 'wpvibes-notice',
                'attributes'      => $this->get_attributes(),
                'supports'        => $this->get_supports(),
                'render_callback' => array( $this, 'render' ),
            )
        );
    }

    // Attribute, supports, and render methods below

Two keys worth pointing out:

style and editor_style - attach the stylesheet registered in the loader (same handle for both). WordPress loads it only when the block is used.
render_callback - the PHP function that returns the block's HTML.

2.2 - Define the attributes

Add this method to the class:

public function get_attributes() {

        return array(

            'title' => array(
                'type'    => 'string',
                'default' => 'Important notice',
                'label'   => __( 'Title', 'wpvibes-blocks' ),
            ),

            'description' => array(
                'type'    => 'string',
                'default' => 'Add your notice message here.',
                'label'   => __( 'Description', 'wpvibes-blocks' ),
            ),

            'skin' => array(
                'type'    => 'string',
                'enum'    => array( 'Alert', 'Warning', 'Success', 'Info' ),
                'default' => 'Info',
                'label'   => __( 'Skin', 'wpvibes-blocks' ),
            ),
        );
    }

Three attributes:

title - a string, so WordPress auto-generates a text input in the sidebar.
description - same, another text input.
skin - string with enum, so WordPress auto-generates a dropdown with exactly those four options.

The label key controls what the user sees. Without it, WordPress derives a label from the attribute name.

2.3 - Add block supports

public function get_supports() {

        return array(
            'autoRegister' => true,
            'color'        => array( 'text' => true, 'background' => true ),
            'spacing'      => array( 'padding' => true, 'margin' => true ),
            'border'       => array( 'color' => true, 'radius' => true, 'style' => true, 'width' => true ),
        );
    }

Two things happen here:

autoRegister => true - the flag that tells WordPress to register this block from PHP alone, without JavaScript scaffolding.
color, spacing, border - turn on native design panels in the sidebar. Users get Color, Spacing, and Border controls automatically.

2.4 - Write the render callback

public function render( $attributes ) {

        $skin_class = 'wpvibes-notice--' . strtolower( $attributes['skin'] );

        $wrapper = get_block_wrapper_attributes(
            array(
                'class' => 'wpvibes-notice ' . $skin_class,
                'role'  => 'alert',
            )
        );

        $title = ! empty( $attributes['title'] )
            ? '<h4 class="wpvibes-notice__title">' . esc_html( $attributes['title'] ) . '</h4>'
            : '';

        $description = ! empty( $attributes['description'] )
            ? '<p class="wpvibes-notice__description">' . esc_html( $attributes['description'] ) . '</p>'
            : '';

        return sprintf(
            '<div %1$s><div class="wpvibes-notice__icon"></div><div class="wpvibes-notice__content">%2$s%3$s</div></div>',
            $wrapper,
            $title,
            $description
        );
    }
}

Key points:

get_block_wrapper_attributes() returns HTML attributes carrying every design choice the user made - color, background, padding, border. Always use it.
esc_html() on all user-provided content. Standard WordPress escaping.
BEM naming - wpvibes-notice (base) plus wpvibes-notice--alert (variant). Predictable CSS.

2.5 - Add the CSS

.wpvibes-notice {
    display: flex;
    align-items: flex-start;
    gap: 12px;
    padding: 16px 20px;
    border-left: 4px solid currentColor;
    border-radius: 4px;
}

.wpvibes-notice--alert   { background: #fee2e2; color: #991b1b; border-left-color: #dc2626; }
.wpvibes-notice--warning { background: #fef3c7; color: #92400e; border-left-color: #f59e0b; }
.wpvibes-notice--success { background: #d1fae5; color: #065f46; border-left-color: #10b981; }
.wpvibes-notice--info    { background: #dbeafe; color: #1e3a8a; border-left-color: #3b82f6; }

💡
Notes: The full CSS (icon circles, title and description typography, hover states) is in the plugin repository at assets/notice.css. Copy the complete file into the plugin's assets/ folder before testing.

2.6 - See it working

Create a new page or post
Click + in the block inserter and search for Notice
Try each skin from the sidebar dropdown
Adjust the native Color and Padding controls

The first PHP-only block is done. No JavaScript. No build step. No block.json.

💡
Notes: The complete file for reference is at blocks/class-notice-block.php.

Step 3: Build the Category Display Block

The Category Display block shows post categories in Grid, List, or Compact layout. For each category: name, post count, an image (from ACF if installed, plugin placeholder otherwise), and a list of recent posts.

This block covers all four supported attribute types - string, integer, boolean, and enum - in one useful example.

3.1 - Create the block class

Create blocks/class-category-display-block.php:

<?php
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class WPVibes_Category_Display_Block {

    public function register() {

        register_block_type(
            'wpvibes/category-display',
            array(
                'title'           => __( 'Category Display', 'wpvibes-blocks' ),
                'description'     => __( 'Display categories with post count, image, and recent posts.', 'wpvibes-blocks' ),
                'category'        => 'widgets',
                'icon'            => 'category',
                'style'           => 'wpvibes-category-display',
                'editor_style'    => 'wpvibes-category-display',
                'attributes'      => $this->get_attributes(),
                'supports'        => $this->get_supports(),
                'render_callback' => array( $this, 'render' ),
            )
        );
    }

    // Attributes, supports, and render methods below

3.2 - Define the attributes (all 4 types)

public function get_attributes() {

        return array(

            // ENUM — dropdown
            'layout' => array(
                'type'    => 'string',
                'enum'    => array( 'Grid', 'List', 'Compact' ),
                'default' => 'Grid',
                'label'   => __( 'Layout', 'wpvibes-blocks' ),
            ),

            // INTEGER — number input with min/max
            'columns' => array(
                'type'    => 'integer',
                'default' => 3,
                'minimum' => 2,
                'maximum' => 4,
                'label'   => __( 'Columns (Grid only)', 'wpvibes-blocks' ),
            ),

            // INTEGER
            'postCount' => array(
                'type'    => 'integer',
                'default' => 5,
                'minimum' => 1,
                'maximum' => 20,
                'label'   => __( 'Posts per Category', 'wpvibes-blocks' ),
            ),

            // STRING — text input (ACF field key)
            'acfFieldKey' => array(
                'type'    => 'string',
                'default' => 'term_featured_image',
                'label'   => __( 'ACF Image Field Key', 'wpvibes-blocks' ),
            ),

            // ENUM — dropdown
            'orderBy' => array(
                'type'    => 'string',
                'enum'    => array( 'Name', 'Post Count', 'Slug' ),
                'default' => 'Name',
                'label'   => __( 'Order By', 'wpvibes-blocks' ),
            ),

            // BOOLEAN — toggle
            'showImage' => array(
                'type'    => 'boolean',
                'default' => true,
                'label'   => __( 'Show Image', 'wpvibes-blocks' ),
            ),

            // BOOLEAN
            'showPostCount' => array(
                'type'    => 'boolean',
                'default' => true,
                'label'   => __( 'Show Post Count', 'wpvibes-blocks' ),
            ),

            // BOOLEAN
            'showRecentPosts' => array(
                'type'    => 'boolean',
                'default' => true,
                'label'   => __( 'Show Recent Posts', 'wpvibes-blocks' ),
            ),

            // BOOLEAN
            'hideEmpty' => array(
                'type'    => 'boolean',
                'default' => true,
                'label'   => __( 'Hide Empty Categories', 'wpvibes-blocks' ),
            ),
        );
    }

What each attribute type teaches:

layout and orderBy - string with enum. WordPress auto-generates dropdowns with exactly those choices.
columns and postCount - integers with minimum and maximum. WordPress auto-generates number inputs that enforce the ranges.
acfFieldKey - a plain string. Text input where the user types the ACF field name.
showImage, showPostCount, showRecentPosts, hideEmpty - booleans. Each becomes a toggle switch in the sidebar.

That's every attribute type WordPress 7.0 auto-generates a control for.

3.3 - Block supports

public function get_supports() {

        return array(
            'autoRegister' => true,
            'align'        => array( 'wide', 'full' ),
            'color'        => array( 'text' => true, 'background' => true ),
            'spacing'      => array( 'padding' => true, 'margin' => true ),
            'border'       => array( 'color' => true, 'radius' => true, 'width' => true, 'style' => true ),
        );
    }

Same as the Notice block, with align added so users can center or full-width the block.

3.4 - Write the render callback

public function render( $attributes ) {

        $order_by_map = array(
            'Name'       => 'name',
            'Post Count' => 'count',
            'Slug'       => 'slug',
        );

        $categories = get_categories(
            array(
                'hide_empty' => ! empty( $attributes['hideEmpty'] ),
                'orderby'    => $order_by_map[ $attributes['orderBy'] ] ?? 'name',
                'order'      => 'ASC',
            )
        );

        if ( empty( $categories ) ) {
            return '<p>' . esc_html__( 'No categories to display.', 'wpvibes-blocks' ) . '</p>';
        }

        $layout       = strtolower( $attributes['layout'] );
        $layout_class = 'wpvibes-category-display--' . $layout;

        $columns_class = ( 'grid' === $layout )
            ? ' wpvibes-category-display--cols-' . absint( $attributes['columns'] )
            : '';

        $wrapper = get_block_wrapper_attributes(
            array(
                'class' => 'wpvibes-category-display ' . $layout_class . $columns_class,
            )
        );

        $items_html = '';

        foreach ( $categories as $category ) {
            $items_html .= $this->render_category_item( $category, $attributes );
        }

        return sprintf(
            '<div %1$s>%2$s</div>',
            $wrapper,
            $items_html
        );
    }

What the render callback does:

Queries categories using the hideEmpty and orderBy attributes
Handles empty state with a friendly message
Builds layout classes - wpvibes-category-display--grid plus wpvibes-category-display--cols-3 for column-based grids
Loops through categories and renders each via a helper method

3.5 - Render a single category

private function render_category_item( $category, $attributes ) {

        $image_html = '';
        if ( ! empty( $attributes['showImage'] ) ) {
            $image_url  = $this->get_category_image_url( $category, $attributes['acfFieldKey'] );
            $image_html = sprintf(
                '<div class="wpvibes-category-display__image"><img src="%s" alt="%s" loading="lazy"></div>',
                esc_url( $image_url ),
                esc_attr( $category->name )
            );
        }

        $count_html = '';
        if ( ! empty( $attributes['showPostCount'] ) ) {
            $count_html = sprintf(
                '<span class="wpvibes-category-display__count">%s</span>',
                sprintf(
                    esc_html( _n( '%d post', '%d posts', $category->count, 'wpvibes-blocks' ) ),
                    (int) $category->count
                )
            );
        }

        $posts_html = '';
        if ( ! empty( $attributes['showRecentPosts'] ) && $category->count > 0 ) {

            $recent_posts = get_posts(
                array(
                    'category'       => $category->term_id,
                    'posts_per_page' => absint( $attributes['postCount'] ),
                    'orderby'        => 'date',
                    'order'          => 'DESC',
                )
            );

            if ( ! empty( $recent_posts ) ) {

                $posts_html .= '<ul class="wpvibes-category-display__posts">';

                foreach ( $recent_posts as $post ) {
                    $posts_html .= sprintf(
                        '<li><a href="%s">%s</a></li>',
                        esc_url( get_permalink( $post ) ),
                        esc_html( get_the_title( $post ) )
                    );
                }

                $posts_html .= '</ul>';
            }
        }

        return sprintf(
            '<div class="wpvibes-category-display__item">%1$s<div class="wpvibes-category-display__content"><h3 class="wpvibes-category-display__name"><a href="%2$s">%3$s</a></h3>%4$s%5$s</div></div>',
            $image_html,
            esc_url( get_category_link( $category ) ),
            esc_html( $category->name ),
            $count_html,
            $posts_html
        );
    }

Each part (image, count, recent posts) is built conditionally based on the toggles. If a toggle is off, that part's HTML variable stays empty and contributes nothing to the final output.

3.6 - The ACF image with fallback

The Category Display block uses an ACF image if the site has ACF installed and the field is set. If not, it falls back to a placeholder from the plugin's own assets folder:

private function get_category_image_url( $category, $acf_field_key ) {

        // Check if ACF is active AND a field key is provided.
        if ( function_exists( 'get_field' ) && ! empty( $acf_field_key ) ) {

            // ACF term meta uses 'category_' . term_id as the object ID.
            $acf_image = get_field( $acf_field_key, 'category_' . $category->term_id );

            if ( $acf_image ) {

                // ACF image field can return an array, an ID, or a URL string
                // depending on the "Return Format" setting.
                if ( is_array( $acf_image ) && ! empty( $acf_image['url'] ) ) {
                    return $acf_image['url'];
                }

                if ( is_string( $acf_image ) ) {
                    return $acf_image;
                }

                if ( is_numeric( $acf_image ) ) {
                    $url = wp_get_attachment_image_url( $acf_image, 'medium' );
                    if ( $url ) {
                        return $url;
                    }
                }
            }
        }

        // Fallback: plugin's placeholder image.
        return WPVIBES_BLOCKS_URL . 'assets/images/category-placeholder.png';
    }
}

Three things this pattern teaches:

function_exists() before using an external plugin's function - always. Never assume ACF (or any plugin) is active.
The ACF term meta prefix - ACF stores term meta under category_ + term_id. This trips up many developers.
Handling ACF's different return formats - ACF image fields can return an array, an ID, or a URL, depending on the "Return Format" setting. The code should handle at least the two common ones.

3.7 - Add the CSS

Create assets/category-display.css with the base structure:

.wpvibes-category-display {
    display: grid;
    gap: 24px;
}

.wpvibes-category-display--grid {
    grid-template-columns: repeat(3, 1fr);
}

.wpvibes-category-display--grid.wpvibes-category-display--cols-2 { grid-template-columns: repeat(2, 1fr); }
.wpvibes-category-display--grid.wpvibes-category-display--cols-4 { grid-template-columns: repeat(4, 1fr); }

.wpvibes-category-display--list    { grid-template-columns: 1fr; }
.wpvibes-category-display--compact { grid-template-columns: 1fr; gap: 0; }

💡
Important: The full CSS (card styling, hover states, image aspect ratios, list-layout flex rules, compact-layout borders, and mobile responsiveness) is in the plugin repository at assets/category-display.css. Copy the complete file into the plugin's assets/ folder before testing.

3.8 - Add a placeholder image

Place any image at assets/images/category-placeholder.png - an 800×450 image works well. The plugin repository includes one; a custom branded placeholder also works.

3.9 - See it working

Assign a few posts to different categories
Insert the Category Display block
In the sidebar, try:

*   Each layout (Grid, List, Compact)

*   Different column counts (2, 3, 4) while in Grid layout

*   Toggling Show Image, Show Post Count, Show Recent Posts

*   Changing Posts per Category

Two production-ready PHP-only blocks - one simple, one covering the full API - done.

💡
Notes: The complete file for reference is at blocks/class-category-display-block.php.

Debugging Tips

When something breaks during development, enable WordPress debug logging in wp-config.php:

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Then check wp-content/debug.log after triggering the issue. Nine times out of ten, a PHP error during registration is the culprit — and it will be in the log with a line number.

For attribute-level debugging (checking what's being passed to the render callback), add temporary error_log() calls at the top of the render function:

error_log( 'Notice block attributes: ' . print_r( $attributes, true ) );

Remove these before shipping.

Get the Full Plugin

The complete plugin - with all CSS, placeholder image, and README - is on GitHub.

How PHP-Only Blocks Work Under the Hood

Now that the plugin builds, here's what actually happens when a PHP-only block is registered and rendered.

Before WordPress 7.0

Building a server-rendered block required these files, at minimum:

my-plugin/
├── src/block/
│   ├── block.json
│   ├── edit.js
│   └── index.js
├── package.json
└── my-plugin.php

The edit.js typically looked like this:

import { ServerSideRender } from "@wordpress/editor";

export default function edit( props ) {
    return (
        <ServerSideRender
            block={ props.name }
            attributes={ props.attributes }
        />
    );
}

A JavaScript component whose only job was to say "please render this on the server." Then npm install, run a build, and hope everything worked.

With WordPress 7.0

WordPress 7.0 adds one flag: autoRegister => true. When set, WordPress:

Takes the block registration from PHP
Adds it to a JavaScript global in the editor settings
The editor picks it up and uses ServerSideRender internally for the preview
When a user changes an attribute, the editor calls the REST API, which runs the PHP render_callback, and swaps in the new HTML

Zero JavaScript written. WordPress handles the ceremony.

The runtime flow

User changes an attribute in the sidebar
        ↓
Editor sends REST API request
        ↓
WordPress runs render_callback in PHP
        ↓
render_callback returns HTML string
        ↓
Editor swaps HTML into the block preview

This is why every attribute change causes a small delay - there's always a server round-trip. That's the deliberate trade-off: no client-side complexity, but no live reactivity either.

Auto-generated inspector controls

WordPress inspects the attributes array and generates sidebar controls automatically:

Attribute definition	Generated control
`type: 'string'`	Text input
`type: 'string'` + `enum: [...]`	Dropdown (SelectControl)
`type: 'integer'` with `minimum` / `maximum`	Number input with enforced range
type: 'boolean'	Toggle switch

Controls are not generated for object and array types, or for attribute names that conflict with reserved block-supports names like style.

When Should You Use PHP-Only Blocks?

An honest decision table:

Use PHP-only blocks when	Use JavaScript-registered blocks when
Block is display-only (notice, category grid, author box)	Block needs InnerBlocks (nested blocks)
Content comes from server data (users, posts, terms, APIs)	Inline rich-text editing is required
Replacing a legacy shortcode	Editor experience needs live client-side reactivity
Avoiding a JavaScript build pipeline	Interactivity API is needed for state management
Simple enough that a server round-trip on each change is acceptable	Real-time visual manipulation (drag handles, instant previews) is essential

Both approaches are first-class WordPress citizens. PHP-only blocks aren't a downgrade -they're a shortcut for a specific class of blocks that never needed JavaScript in the first place.

What Are the Limitations of PHP-Only Blocks?

Deliberate scope decisions, not bugs. Knowing them helps pick the right approach.

Limitation	Impact	Status
No InnerBlocks / nested blocks	Can't build columns, accordions, sections	No timeline announced
Only 4 attribute types (string, integer, boolean, enum)	No media picker, rich text, date picker	DataForm being extended to PHP-only blocks in 7.1
Block Bindings limited in 7.0	Custom fields, post meta bindings need workarounds	ACF and Meta Box become native binding sources in 7.1
Server round-trip on every attribute change	Preview feels less responsive than JS blocks	By design - the trade-off for zero JavaScript
Custom `style` attribute conflicts with supports	Must rename to `skin`, `variant`, etc.	Reserved namespace, not a bug

Frequently Asked Questions

Can PHP-only blocks contain InnerBlocks?

No. PHP-only blocks cannot contain nested blocks. For layouts like columns, accordions, or sections that wrap other blocks, use the traditional JavaScript block registration path.

Do PHP-only blocks work with the Interactivity API?

Not directly. The Interactivity API is designed for client-side state and reactivity, which PHP-only blocks don't provide. For blocks needing state (toggles, tabs, live filtering), JavaScript block registration is the correct choice.

Which attribute types get auto-generated controls?

Four types: string (text input), string with enum (dropdown), integer with minimum/maximum (number input), and boolean (toggle). Types like object and array do not generate controls.

Why is my custom style attribute causing errors?

WordPress reserves the style attribute name when block supports for color, spacing, or typography are enabled. Rename any custom attribute called style to something like skin, variant, or theme.

Does the editor preview update in real time?

No. Each attribute change triggers a REST API call to the PHP render_callback, then the editor swaps in the returned HTML. There's a small delay on every change - this is the trade-off for not writing JavaScript.

Can I use wp_enqueue_block_style() for PHP-only block CSS?

Not reliably. wp_enqueue_block_style() works for JavaScript-registered blocks but doesn't always fire for PHP-only blocks in the editor. Use wp_register_style() with the style and editor_style keys inside register_block_type() instead - the pattern shown in this guide.

What happens in the editor if the render callback throws an error?

The block shows "Error loading block" in the editor preview. Check wp-content/debug.log for the PHP error - the line number points directly to the issue.

Do PHP-only blocks support WordPress block themes and Full Site Editing?

Yes. PHP-only blocks work in block themes, templates, template parts, and the Site Editor. WordPress 7.1 enforces iframe mode for block themes - the examples in this guide use current APIs, so no changes are needed.

Wrapping Up

Building the WPVibes Blocks plugin has covered:

autoRegister => true is the entire "new API." Everything else is standard register_block_type().

The style and editor_style keys with wp_register_style() are the right way to attach CSS to a PHP-only block — cleaner and correctly loading in both editor and frontend.

get_block_wrapper_attributes() carries all block-supports styles into the render output. Always use it.

Auto-generated sidebar controls work well within their limits - string, integer, boolean, enum.

Server round-trip on every attribute change is the trade-off - keep render callbacks fast.

One file per block scales. Adding a new block later is one new file, one line in the loader.