Tutorial: Build your first block

In this tutorial, you will build a “Copyright Date Block”—a basic yet practical block that displays the copyright symbol (©), the current year, and an optional starting year. This type of content is commonly used in website footers.

The tutorial will guide you through the complete process, from scaffolding the block plugin using the create-block package to modifying each file. While previous WordPress development experience is beneficial, it’s not a prerequisite for this tutorial.

By the end of this guide, you will have a clear understanding of block development fundamentals and the necessary skills to create your own WordPress blocks.

What you’re going to build

Here’s a quick look at what you’re going to build.

You can also interact with the finished project in WordPress Playground or use the Quick Start Guide to install the complete block plugin in your local WordPress environment.

Prerequisites

To complete this tutorial, you will need:

1. Code editor
2. Node.js development tools
3. Local WordPress environment

If you don’t have one or more of these items, the Block Development Environment documentation will help you get started. Come back here once you are all set up.

Scaffolding the block

The first step in creating the Copyright Date Block is to scaffold the initial block structure using the @wordpress/create-block package.

You can use create-block from just about any directory (folder) on your computer and then use wp-env to create a local WordPress development environment with your new block plugin installed and activated.

Therefore, choose a directory to place the block plugin or optionally create a new folder called “Block Tutorial”. Open your terminal and cd to this directory. Then run the following command.

npx @wordpress/create-block@latest copyright-date-block --variant=dynamic
cd copyright-date-block

After executing this command, you’ll find a new directory named copyright-date-block in the plugins folder. This directory contains all the initial files needed to start customizing your block.

This command also sets up the basic structure of your block, with copyright-date-block as its slug. This slug uniquely identifies your block within WordPress.

Navigate to the Plugins page in the WordPress admin and confirm that the plugin is active. Then, create a new page or post and ensure you can insert the Copyright Date Block. It should look like this once inserted.

Reviewing the files

Before we begin modifying the scaffolded block, it’s important to review the plugin’s file structure. Open the plugin folder in your code editor.

Next, look at the File structure of a block documentation for a thorough overview of what each file does. Don’t worry if this is overwhelming right now. You will learn how to use each file throughout this tutorial.

Initial setup

Let’s start by creating the simplest Copyright Date Block possible, which will be a dynamically rendered block that simply displays the copyright symbol (©) and the current year. We’ll also add a few controls allowing the user to modify font size and text color.

Before proceeding to the following steps, run npm run start in the terminal from within the plugin directory. This command will watch each file in the /src folder for changes. The block’s build files will be updated each time you save a file.

Check out the Working with JavaScript for the Block Editor documentation to learn more.

Updating block.json

Open the block.json file in the /src folder.

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "create-block/copyright-date-block",
    "version": "0.1.0",
    "title": "Copyright Date Block",
    "category": "widgets",
    "icon": "smiley",
    "description": "Example block scaffolded with Create Block tool.",
    "example": {},
    "supports": {
        "html": false
    },
    "textdomain": "copyright-date-block",
    "editorScript": "file:./index.js",
    "editorStyle": "file:./index.css",
    "style": "file:./style-index.css",
    "render": "file:./render.php",
    "viewScript": "file:./view.js"
}

Since this scaffolding process created this file, it requires some updating to suit the needs of the Copyright Date Block.

Modifying the block identity

Begin by removing the icon and adding a more appropriate description. You will add a custom icon later.

1. Remove the line for icon
2. Update the description to “Display your site’s copyright date.”
3. Save the file

After you refresh the Editor, you should now see that the block no longer has the smiley face icon, and its description has been updated.

Adding block supports

Next, let’s add a few block supports so that the user can control the font size and text color of the block.

Update the supports section of the block.json file to look like this.

"supports": {
    "color": {
        "background": false,
        "text": true
    },
    "html": false,
    "typography": {
        "fontSize": true
    }
},

Note that when you enable text color support with "text": true, the background color is also enabled by default. You are welcome to keep it enabled, but it’s not required for this tutorial, so you can manually set "background": false.

Save the file and select the block in the Editor. You will now see both Color and Typography panels in the Settings Panel. Try modifying the settings and see what happens.

Removing unnecessary code

For simplicity, the styling for the Copyright Date Block will be controlled entirely by the color and typography block supports. This block also does not have any front-end JavaScript. Therefore, you don’t need to specify stylesheets or a viewScript in the block.json file.

1. Remove the line for editorStyle
2. Remove the line for style
3. Remove the line for viewScript
4. Save the file

Refresh the Editor, and you will see that the block styling now matches your current theme.

Putting it all together

Your final block.json file should look like this:

{
    "$schema": "https://schemas.wp.org/trunk/block.json",
    "apiVersion": 3,
    "name": "create-block/copyright-date-block",
    "version": "0.1.0",
    "title": "Copyright Date Block",
    "category": "widgets",
    "description": "Display your site's copyright date.",
    "example": {},
    "supports": {
        "color": {
            "background": false,
            "text": true
        },
        "html": false,
        "typography": {
            "fontSize": true
        }
    },
    "textdomain": "copyright-date-block",
    "editorScript": "file:./index.js",
    "render": "file:./render.php"
}

Updating index.js

Before you start building the functionality of the block itself, let’s do a bit more cleanup and add a custom icon to the block.

Open the index.js file. This is the main JavaScript file of the block and is used to register it on the client. You can learn more about client-side and server-side registration in the Registration of a block documentation.

Start by looking at the registerBlockType function. This function accepts the name of the block, which we are getting from the imported block.json file, and the block configuration object.

import Edit from './edit';
import metadata from './block.json';

registerBlockType( metadata.name, {
    edit: Edit,
} );

By default, the object just includes the edit property, but you can add many more, including icon. While most of these properties are already defined in block.json, you need to specify the icon here to use a custom SVG.

Adding a custom icon

Using the calendar icon from the Gutenberg Storybook, add the SVG to the function like so:

const calendarIcon = (
    <svg
        viewBox="0 0 24 24"
        xmlns="http://www.w3.org/2000/svg"
        aria-hidden="true"
        focusable="false"
    >
        <path d="M19 3H5c-1.1 0-2 .9-2 2v14c0 1.1.9 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm.5 16c0 .3-.2.5-.5.5H5c-.3 0-.5-.2-.5-.5V7h15v12zM9 10H7v2h2v-2zm0 4H7v2h2v-2zm4-4h-2v2h2v-2zm4 0h-2v2h2v-2zm-4 4h-2v2h2v-2zm4 0h-2v2h2v-2z"></path>
    </svg>
);

registerBlockType( metadata.name, {
    icon: calendarIcon,
    edit: Edit
} );

Save the