Enhancing WordPress Gutenberg Blocks: Add Image Upload Feature

At Sreyas IT Solutions, we specialize in delivering custom WordPress solutions that combine functionality, flexibility, and ease of use. With years of experience developing tailored Gutenberg blocks and user-friendly interfaces, we continuously strive to enhance the editorial experience for our clients and their content teams.

As part of our ongoing commitment to improving custom block capabilities, this documentation outlines the development of Image Upload Feature for the Simple Header block. This enhancement introduces a user-friendly image upload option directly in the block sidebar (Inspector Controls), allowing editors to seamlessly insert or change header visuals without needing to leave the block editing view. Leveraging native Gutenberg components such as MediaUpload, InspectorControls, and RichText, we ensure a cohesive and intuitive editing workflow.

 Features Added

• Attribute Added
  • imageUrl
    Type: string
    Purpose: Stores the URL of the uploaded image. Used to display the image inside the block.
    

• UI Components Used
  • MediaUpload – Allows image uploading and selection.
  • InspectorControls – Enables adding settings in the block sidebar.
  • PanelBody, Button – For UI structure and interaction within the sidebar.
    

• Sidebar Integration

The MediaUpload button is wrapped inside InspectorControls > PanelBody, making it accessible from the sidebar when the block is selected in the editor.

<InspectorControls>
  <PanelBody title="Image Settings" initialOpen={true}>
    <MediaUpload
      onSelect={(media) => setAttributes({ imageUrl: media.url })}
      allowedTypes={['image']}
      render={({ open }) => (
        <Button onClick={open} isSecondary>
          {imageUrl ? 'Change Image' : 'Upload Image'}
        </Button>
      )}
    />
  </PanelBody>
</InspectorControls>

• Image Display

The image is conditionally rendered within the block preview and saved output using:

{imageUrl && <img src={imageUrl} alt="Header Image" />}

Block Configuration (block.json)

{
  "apiVersion": 2,
  "name": "sreyas/simple-header",
  "title": "Simple Header with Image",
  "category": "widgets",
  "icon": "heading",
  "description": "Custom header with image upload.",
  "attributes": {
    "title": {
      "type": "string",
      "source": "html",
      "selector": "h1"
    },
    "header": {
      "type": "string",
      "source": "html",
      "selector": "h2"
    },
    "subtitle": {
      "type": "string",
      "source": "html",
      "selector": "h3"
    },
    "imageUrl": {
      "type": "string",
      "default": ""
    }
  },
  "editorScript": "file:./build/index.js"
}

 Block Logic (src/index.js)

 Edit Function

• Allows editing of title, header, and subtitle using RichText.
• Displays image upload option in sidebar via InspectorControls.
• Shows uploaded image inside the block preview.
  

Save Function

• Outputs structured HTML containing title, header, subtitle, and the image if it exists.

Sample Code

Updated block.json

{
  "apiVersion": 2,
  "name": "sreyas/simple-header",
  "title": "Simple Header with Image",
  "category": "widgets",
  "icon": "heading",
  "description": "Custom header with image upload.",
  "attributes": {
    "title": {
      "type": "string",
      "source": "html",
      "selector": "h1"
    },
    "header": {
      "type": "string",
      "source": "html",
      "selector": "h2"
    },
    "subtitle": {
      "type": "string",
      "source": "html",
      "selector": "h3"
    },
    "imageUrl": {
      "type": "string",
      "default": ""
    }
  },
  "editorScript": "file:./build/index.js"
}

Updated src/index.js

import { registerBlockType } from '@wordpress/blocks';
import {
  RichText,
  MediaUpload,
  InspectorControls,
  useBlockProps,
} from '@wordpress/block-editor';
import { PanelBody, Button } from '@wordpress/components';
import { __ } from '@wordpress/i18n';

registerBlockType('sreyas/simple-header', {
  edit({ attributes, setAttributes }) {
    const { title, header, subtitle, imageUrl } = attributes;
    const blockProps = useBlockProps();

    return (
      <>
        <InspectorControls>
          <PanelBody title={__('Image Settings', 'simple-header')} initialOpen={true}>
            <MediaUpload
              onSelect={(media) => setAttributes({ imageUrl: media.url })}
              allowedTypes={['image']}
              render={({ open }) => (
                <Button onClick={open} isSecondary>
                  {imageUrl ? __('Change Image', 'simple-header') : __('Upload Image', 'simple-header')}
                </Button>
              )}
            />
          </PanelBody>
        </InspectorControls>

        <div {...blockProps}>
          <RichText
            tagName="h1"
            value={title}
            onChange={(value) => setAttributes({ title: value })}
            placeholder={__('Enter title', 'simple-header')}
          />
          <RichText
            tagName="h2"
            value={header}
            onChange={(value) => setAttributes({ header: value })}
            placeholder={__('Enter header', 'simple-header')}
          />
          <RichText
            tagName="h3"
            value={subtitle}
            onChange={(value) => setAttributes({ subtitle: value })}
            placeholder={__('Enter subtitle', 'simple-header')}
          />
          {imageUrl && <img src={imageUrl} alt={__('Header Image', 'simple-header')} />}
        </div>
      </>
    );
  },

  save({ attributes }) {
    const { title, header, subtitle, imageUrl } = attributes;
    const blockProps = useBlockProps.save();
    return (
      <div {...blockProps}>
        <h1>{title}</h1>
        <h2>{header}</h2>
        <h3>{subtitle}</h3>
        {imageUrl && <img src={imageUrl} alt="Header Image" />}
      </div>
    );
  },
});

 Summary

The addition of the image upload feature significantly boosts the visual customization potential of the Simple Header block. By enabling image selection from the sidebar, users can quickly personalize headers without any technical barriers—empowering marketers, content creators, and site admins alike.

Sreyas’ deep expertise in block-based development and modern WordPress architecture, this upgrade offers a more dynamic and visually compelling user experience. This feature is particularly beneficial for websites seeking to maintain brand consistency while also enabling non-technical users to easily manage content visuals—saving both time and development overhead in the long run.