Images in a WordPress theme serve two fundamentally different roles:

1. Content Images (Dynamic CMS Media): Blog post featured images, portfolio galleries, author avatars, and product photography uploaded by content editors via the WordPress Media Library.
2. Design Assets (Static Theme Media): Brand logos, UI illustrations, background textures, and placeholder graphics bundled directly inside your theme codebase.

In traditional WordPress PHP themes, rendering an image responsibly requires nesting complex functions (wp_get_attachment_image, wp_get_attachment_image_src, wp_calculate_image_srcset, wp_calculate_image_sizes). In pure React applications, developers often use basic <img /> tags that fail to integrate with WordPress's media database.

ForgeWP solves this with <WpImage> from @forgewp/react. It provides an isomorphic, type-safe React component in development that compiles to high-performance WordPress wp_get_attachment_image() calls or get_theme_file_uri() in production.

1. How <WpImage> Works Across Environments

The following diagram illustrates how <WpImage> bridges local Vite development with native WordPress server rendering:

1. In Local Development (pnpm dev): <WpImage> reads image mock data from cms/mock-data.ts through the React WpPostContext. If an image is missing or you use a random seed, it automatically displays a responsive placeholder so you can style your layout immediately.
2. At Compile & Export (pnpm export): The compiler analyzes <WpImage> attributes and transforms the tag into native WordPress PHP (wp_get_attachment_image or get_theme_file_uri).
3. On the Live WordPress Server: For a Media Library attachment, the generated PHP calls WordPress image functions, which use the site's registered image sizes and responsive attributes. Static theme assets follow a separate path.

2. Quick Decision Guide: Which Prop to Use?

Before diving into details, use this quick reference matrix to choose the right <WpImage> prop for your media:

3. Rendering Post Featured Images (field="featuredImage")

The most common use case for <WpImage> is rendering the featured image (post thumbnail) of an article or custom post type.

Basic Implementation

What the Compiler Outputs in PHP

When you export your theme, the JSX above compiles directly to:

Notice that:

• It calls WordPress's native wp_get_attachment_image().
• WordPress automatically populates the srcset attribute with all image dimensions generated upon upload (thumbnail, medium, medium_large, large).
• It preserves your Tailwind CSS classes in the output HTML.

3. Rendering Static & Local Assets with src

Beyond dynamic CMS uploads, you will frequently need to render static theme graphics: brand logos, decorative backgrounds, hero vectors, or bundled illustrations.

<WpImage> supports the src prop in three flexible ways:

Pattern A: Static Asset Import (Vite-Hashed)

When you import an image file directly from src/assets/, Vite treats it as a static asset module:

Pattern B: Absolute Path from public/

For static files stored in your project's public/ directory (e.g. public/assets/logo.svg):

Pattern C: External CDN or Remote URLs

You can pass any fully qualified remote URL (https://...):

4. How the Compiler Identifies Images (Demystifying the "Magic")

Developers often ask: How does ForgeWP know whether to compile <WpImage> into a WordPress PHP function or a static HTML tag?

There is no black magic. The compilation pipeline operates in two clean, deterministic stages:

Stage 1: Server-Side Pre-Rendering (Intermediate Custom Element)

During pnpm export, ForgeWP evaluates your React components in a Node.js SSR context with _forgeWpCompileTime = true.

Instead of emitting a normal <img> tag, <WpImage> renders a temporary custom XML marker:

If you used src="/assets/logo.svg", it produces:

Stage 2: The Markup Processor's 5-Branch Evaluation

Next, ForgeWP's compiler engine (markup-processor.js) parses all <forgewp-image> tags and executes a deterministic branching rule:

5. WordPress Image Sub-Sizes (size)

WordPress automatically generates multiple cropped versions of every uploaded image. You can specify which registered image size <WpImage> should request using the size prop:

6. Custom Field & ACF Image Attachments

Themes frequently display secondary images attached to posts via custom fields or Advanced Custom Fields (ACF)—such as author portraits, product galleries, or sponsor logos.

Pass the meta key name to the field prop:

Smart Isomorphic Resolution for Custom Fields

In WordPress, custom fields can store images in two ways:

1. As an Attachment ID (integer, e.g. 142): The compiler outputs a PHP check that calls wp_get_attachment_image(142, 'thumbnail', ...) with full responsive srcset.
2. As a Direct URL string (https://...): If the field stores a raw URL string, the compiler falls back to <img src="..." /> with escaped attributes.

7. Performance Optimization: priority & Core Web Vitals

Largest Contentful Paint (LCP) is one of Google's most critical Core Web Vitals metrics. Browsers penalize sites that lazy-load above-the-fold hero images.

ForgeWP provides the priority prop:

When priority={true} is set:

1. fetchpriority="high" is added to prioritize network downloading in Chromium browsers.
2. loading="eager" is applied (disabling native lazy loading).
3. The compiler may also add a preload for a statically resolved image source. For dynamic WordPress attachment fields, inspect the generated output to check preload behavior.

For standard below-the-fold content images, omit priority (or specify loading="lazy"). The component defaults to lazy loading and asynchronous decoding.

8. Complete Props Reference for <WpImage>

Common Questions & FAQs

Next Step: Local Assets, SVGs & Dynamic Icons

Proceed to Local Assets, SVGs & Dynamic Icons to learn how to bundle theme assets from public/ and src/assets/, render vector graphics, and use the tree-shaken <WpIcon> primitive!