The WordPress Block Directory: The Essential Guide

The WordPress block directory is a new way that WordPress users can discover, install and test third-party WordPress blocks from within the WordPress block editor. Introduced in WordPress 5.5, the WordPress Block Directory makes it easier to find the WordPress block that best fits your needs.

If you haven’t yet heard of the WordPress block directory, you’re not alone. In this guide, we’ll cover everything you need to know about the new block directory. We’ll also explain how to start using the Block Director to streamline your content workflow.In this Guide

What is the WordPress Block Directory?

The WordPress Block Directory is a category of free WordPress plugins that provide third-party WordPress blocks for use within the WordPress block editor.

The new WordPress block directory is built right into the block editor, so you can install new block types to your site without ever leaving the editor. The block directory is designed to make it easier for users to search and install WordPress blocks directly from the block editor, so you can quickly add the type of block you need into your content.

wordpress block directory

To search the WordPress block directory, use the “+” icon on the top left of the page to use the new block inserter and search for available blocks.

Here are a few important things to note about the WordPress block directory:

  • The block directory search functionality is only available to WordPress user roles who have the permission to add or install plugins.
  • If you add a third-party block from the block directory, the corresponding WordPress plugin will be installed on your site. So if you see a new plugin installed on your website, and you don’t remember installing it, check to see if the plugin is a WordPress block plugin.
  • The WordPres block directory pulls in both built-in default WordPress blocks and third-party WordPress block plugins so you can install them directly from your page/post editor.
  • Search results of third-party block plugins depend a few requirements that developers must meet (covered in more detail later in this article).

History of the WordPress Block Directory

The WordPress block directory is the result of WordPress core discussions about how block plugins need to be distinguished from other free plugins available on the plugin directory.

The WordPress block directory endeavor was a cross-team development effort that involved major updates on:

  • The WordPress plugin update processes
  • The WordPress plugin repository
  • Integration into the WordPress block editor’s Inserter

The 8.4 version of the featured Gutenberg WordPress plugin was when the block directory was merged into the WordPress core; on August 11, 2020 in WordPress 5.5.

The Purpose of WordPress Block Directory

new WordPress block directory is included in the main plugin directory, so you’re either browsing regular WordPress plugins or single block-enabled plugins.

The block directory is designed to help distinguish block plugins, which are javascript-only and register only WordPress blocks, versus traditional WordPress plugins that have more functionality.

What Are WordPress Blocks?

WordPress blocks are page elements that you can use from within the WordPress block editor to help organize and design the content of your blog posts and pages. From images to quotes to lists and media embeds, there’s a WordPress block for just about everything.

wordpress block library

Built-in Default WordPress Blocks

WordPress comes with a library of built-in default blocks. Here’s a table of some of the most frequently-used blocks. This table includes some of the default WordPress blocks included with WordPress in the new block editor.

WordPress blockDescription
AudioEmbed a simple audio player.
ButtonsDrive conversions with beautiful buttons.
CategoriesDisplay a list of all categories.
ClassicUse the classic WordPress editor
CodeDisplay code snippets that respect your spacing and tabs.
ColumnsAdd a block that displays content in multiple columns, then add whatever content blocks you’d like.
CoverAdd an image or video with a text overlay – great for headers.
EmbedEmbed videos, images, tweets, audio, and other content from external sources.
FileAdd a link to a downloadable file.
GalleryDisplay multiple images in a rich gallery.
HeadingIntroduce new sections and organize content to help visitors (and search engines) understand the structure of your content.
ImageInsert an image to make a visual statement.
Latest postDisplay a list of your most recent posts.
ListCreate a bulleted or numbered list.
ParagraphThe building block of all narrative.
Pull quoteGive special visual interest to a quote from your text.
QuoteGive quoted text visual emphasis.
MoreAdds a “Read more” element
SeparatorCreate a break between ideas or sections with a horizontal separator.
ShortcodeInsert additional custom elements with WordPress shortcodes.
SpacerAdd white space between blocks and customize height.

When you login to your Admin dashboard (assuming that you’re using WordPress 5.0 or higher) and click to write a new post, immediately you’ll notice a panel for content editing that’s based on blocks.

Previously, this section of your post editor was one big content field that contained standard text formatting controls.

When comparing the old version of the editor to the new block-based version, this was a major upgrade for users.

The overall editing experience within the new version is a lot more streamlined and free of distractions. It gives you clear visibility to your main “canvas” without other elements that were mostly unneeded.

WordPress Block Library Plugins

In addition to the built-in WordPress blocks, other plugins like Kadence Blocks add even more blocks to the WordPress block library. The Kadence Blocks plugin adds even more power to the block editor, adding page builder features.

For example, Kadence Blocks custom blocks include:

  • Row Layout – Create rows with nested blocks either in columns or as a container. Give style to your rows with a background, overlay, padding, etc.
  • Advanced Gallery – Create stunning photo galleries, carousels, and sliders! Enable custom links, captions, and more. Plus you can select the image size for performance.
  • Form – Our powerful form block allows you to easily create a contact or marketing form and style it within the block editor. 
  • Advanced Text – Create a heading or paragraph and define sizes for desktop, tablet and mobile along with font family, colors, etc.
  • Advanced Button – Create an advanced button or a row of buttons. Style each one, including hover controls. Plus you can use an icon and display them side-by-side.
  • Tabs – Create custom vertical or horizontal tabs with advanced styling controls. Each tab content is an empty canvas able to contain any other blocks.
  • Accordion – Create beautiful accordions! Each pane is able to contain any other block, customize title styles, content background, and borders.
  • Testimonials – Create confidence in your brand or product by showing off beautiful and unique testimonials. Display add as a carousel or a grid. 
  • Icon – Choose from over 1500+ SVG icons to add into your page and style the size, colors, background, border, etc. You can also add multiple icons side-by-side.
  • Spacer / Divider – Easily create a divider and determine the space around it or just create some space in your content. You can even define the height per screen size.
  • Info Box – Create a box containing an icon or image and, optionally, a title, description, and learn more text. Style static and hover separately.
  • Icon List – Add beautiful icons to your lists and make them more engaging and attract viewers’ attention. Over 1500 icons to choose from and unlimited styles.
  • Countdown – Increase your conversions by adding a sense of urgency to your offering. Pro includes evergreen campaigns as well.
  • Posts – Display a clean grid of posts anywhere on your site, great for your homepage where you want to tease your blog.
  • Table of Contents – Allow your readers to navigate your content easily with a table of contents block. Includes smooth scroll to anchor.
  • Lottie Animation – You can import lottie animations into your site. You can choose how the animation plays and control animation speeds, loops, etc.
  • Count Up – An animated count up or down to a certain value. Great for displaying stats.
  • Google Maps – Embed a Google Map on your site.
  • Advanced Image – An image block with greater controls and advanced features.

What is a WordPress Block Plugin?

A WordPress block plugin is a relatively small, simple WordPress plugin that provides a single WordPress block. The plugin is the block, essentially.

The WordPress block directory helps organize third-party block plugins in a category separate from traditional WordPress plugins so they are easier to search and install.

For example, the Donation Form Block for Stripe by GiveWP adds a Stripe-powered donation form to your website in a few seconds with a single WordPress block. Once installed, the block is easily inserted into your WordPress website and is designed to be easily customized to fit your needs.

What are Block-Enabled Plugins?

In a nutshell, block-enabled plugins are “traditional” WordPress plugins that include blocks you can use within the block editor. The WordPress plugin directory has also started distinguishing “Block-enabled plugins” to highlight plugins that utilize block functionality.

You will see these labeled as “Plugins categorized as blocks” and can be browsed at

How Do You Use WordPress Blocks?

As you start working on new content for your site, whether it’s a new page or a blog post, you’ll notice that every content piece you include (such as an image or a paragraph of text) is converted into its own block.

You can basically think of a block like a wrapper that’s placed around each piece of content that you include on your post or page. But the block system doesn’t change anything about the content pieces individually, or how they appear on your website. An image is still an image and doesn’t appear any different to the end-user.

You’ll find that creating content with blocks is highly intuitive. When you start creating a new page or post, WordPress invites you to choose your block type or begin writing text.

When you complete a paragraph of text, hit enter and WordPress automatically transitions you to a new block.

When you want to add a different block besides a text paragraph, simply click the “+” icon, located within the block editor in the upper-left corner.

Each block type available for you to choose from is highly customizable in many ways. With a little time and experimentation, you’ll be able to make any block look exactly how you envisioned.

Benefits of the Block Editor

The introduction of the block-based editor has brought a number of benefits to WordPress content creators.

First, you can much more easily rearrange your blocks within each page than the previous editor allowed you to do. Every block has individual controls that allow you to move the block up or down one spot. You can also use the drag and drop function to move blocks around manually.

In previous WordPress editors, moving content around was a pain. First, you had to cut and paste content into the areas that you wanted to put them. Often, doing this caused a lot of formatting issues; although more so with some text editors than others. At times, users would lose entire content sections prior to moving them because they accidentally copied over it in their clipboard.

WordPress block editor

These aren’t issues that you’ll experience with blocks, and they’re a lot more maneuverable as well.

How Do I Use the WordPress Block Directory?

Now that we’ve discussed what WordPress Blocks are, let’s look into the new WordPress block directory.

The idea behind the block directory is not that complicated. But it’s highly useful for developers and site designers once they understand how to properly utilize the tool.

When a WordPress user wants to use a block that’s not available in the default WordPress blocks available locally in their editor, they can head to the search field of the Inserter and type in a keyword, such as “menu” or “team.”

search wordpress blocks

Behind the scenes, the intuitive system first runs a search on the user’s local site. If it’s unable to find the specific block that’s being searched for, it starts searching the block directory: A designated part of the overall WordPress plugin repository that houses single block plugins.

When the system finds blocks that match the current search term, those blocks are displayed within the Inserter, with a preview section available for the user to review.

At this point, the designer decides which block they want to utilize, then clicks on the “Add Block” button. This causes a single-block plugin to be installed and activated, while the designer continues creating the post or page.

If the first block selection wasn’t the best choice, a user can then go back and search for a different block that can also be installed. This allows users a quick and easy way to test different block elements in their designs.

Keep in mind that the block directory can only be accessed by content creators that have full site rights and privileges to install and activate WordPress plugins.

Searching for WordPress Blocks

The search function works really well. The only problem is the current lack of plugins in the repository. It’s important to remember that the block directory is still very new and it’s overall functionality isn’t finalized.

Designers Steven Dufresne and Enrique Sanchez (along with others) have been actively exploring different considerations and variations of the flow for searching, selecting and installing block plugins within the editor.

For example, what happens when a user runs a search and a block plugin shows up in the Inserter that the user already has installed in their editor? Should it display “Disable Block” for that particular search result?

What if the search result displays a block plugin that the user has installed but deactivated? Should it display “Activate Block” for this result?

As you can see, there are many questions that remain up in the air regarding block searches and how they’re delivered.

The discussion is onoging with the designers and developers.

WordPress Block Directory Search Performance Factors

For the WordPress block directory to work, there are several factors that need to perfectly align.

First, the Directory has to have a unique section that’s designated only for single-block plugins to populate the search. There are many plugins that have two or more blocks that cannot be allowed to show in the block directory search feed.

After this, the Directory search feature must return its results within a format that can be displayed in the Inserter.

The block editor then has to run a process that searches the WordPress Plugin directory by way of REST-API. Then, the Inserter requires a method that will allow it to install and activate site plugins.

To do this, it must be able to consider the current user’s site privileges. Only site administrators have the ability to install and activate plugins.

WordPress Block Directory Search Results: Requirements

For a plugin author to have their plugin be a part of the block directory, they have to provide a block.json file and an image to be displayed in the search results. It’s also important for plugin authors to remember that users will need additional information about the plugin, in the preview area, before they decide to download it.

In most cases, a user will want to see a plugin’s:

  • User ratings
  • Author information
  • Date of last plugin update

This helps push forward the decision-making process for users trying to decide which blocks to use on their site. After all, a lot of people don’t decide on things based only on how they look. They want to know what’s under the hood as well.

For the block editor, it would be a good idea (although an extremely difficult proposition that will no doubt require a lot of tweaking down the road) to automatically monitor the discarded plugins and make sure that unused blocks are uninstalled from the site after saving the post.

It’s also important to avoid the potential of a “block graveyard” within the site. With an updated Block Manager, this problem should be solved. It was talked about last year by Mel Choyce-Dawn as a part of the initial block directory designs. But it wasn’t a part of the initial release.

WordPress Single Block Plugins List

If you head over to the WordPress plugin repository, you’ll be able to browse WordPress block-enabled plugins that will feed your search results within the WordPress block editor.

At the time of this writing, there are only six pages of results available to browse. And in reality, only about half of those showing in the plugin repository search are actually going to be visible within the block editor via the Inserter.

With a quick spot check, it seems like a lot of them are completely missing the required block.json files. In those cases, the plugins will not be visible in the WordPress block editor search results, but you will see them in the WordPress plugin repository.

This seems to be improving within the last month, however, as final requirements have been more thoroughly documented and key guidelines published. A lot more of the plugin authors are starting to update their plugins to make sure they’re 100% searchable within the block editor.

Some examples of current, fully tested single-block plugins on the block directory include the Donation Form Block for Stripe by GiveWP.

How To Install a New WordPress Block

The block installation process should be seamless and intuitive for the user. At least it should be in theory.

Basically, all a user needs to do is to click on the “Add Block” button without ever exiting the block editor. The desired new block then immediately becomes available.

You’ll probably find out that in some cases you’ll get an error message that will ask you to try the installation again. But before you do, make sure to check and see if the plugin actually was installed and the block available for use.

In many cases, it seems like the error message is, in and of itself, an error and the block is ready to go. As time moves on, more of these minor bugs will be worked out and this useful new feature called the WordPress block directory will be running smoothly.

Block Directory Plugin Author Guidelines

Near the end of 2019, the Meta Team Lead Alex Sheils published an initial draft of WordPress block plugin guidelines for those who want to have a plugin added to the block Directory. It has since been updated with more detailed requirements as of just a few months ago.

To sum up the key points, plugins on the block Directory must have these specific characteristics:

  • Contain only one single block
  • Not have UI outside of the post editor
  • Have a minimum amount of server-side code
  • Must be structured according to certain specs and include a readme.txt file

Some additional rules that governed the first release of the block directory have been met with some controversy by plugin authors, due to how strict the rules were. However, the restrictions on the Directory weren’t intended on stifling plugin creators.

The goal is to keep the types of blocks that return into the block editor restricted to a specific protocol and type.

That was especially important on the initial release, where it wasn’t a case where more results would be better. The results needed to be very specific within the Inserter.

Knowing that, these additional rules apply to all plugin authors that want to get their plugin on the WordPress block directory:

  • Block plugins are created to use in the Block Editor
  • Block plugins must be separate blocks
  • The title of the plugin must reflect the title of the block
  • The plugin has to include a specific block.json file
  • The plugin author cannot charge a fee or require payment for funcationality. Paid accounts also are not allowed
  • The plugin should be able to function independently
  • It cannot, in any way, promote other plugins, themes or blocks

Think about the block directory sort of like an immature plant that you’ve just put into the ground. You know that you need to watch it and protect it so that it’ll grow into a bigger and better version of itself.

The block directory is no different.

As the design and development team continues to watch, listen and problem-solve, the Directory will begin to evolve into a place where plugin authors and users find a lot of value.

If you’re a plugin author and your plugin doesn’t yet meet the requirements to be on the block directory, keep in mind that it’s still welcomed on the normal WordPress plugins directory.

The Future of the WordPress Block Directory and Block-Enabled Plugins

The block directory has the potential to really extend the design functionality of the WordPress platform. It gives content creators a quick and streamlined way to extend their content creation capabilities with fingertip access to dozens of useful single blocks.

Even with the continuously moving parts, the first release of the block directory is a major milestone that should be celebrated by content creators and plugin authors alike.

Those of you reading this around the time of its publishing are on the cutting edge of the block directory and what it’s going to become. Now is a great time for you to consider some additional WordPress training that will show you other areas of WordPress, like the block directory, that you haven’t yet discovered.

As you continue to grow through the learning curve while turning your site into the success that you envision, remember that mistakes can (and will) happen. That’s why it’s so important to have a WordPress backup plugin and WordPress security plugin protecting your site at all times.

With everything in place, your website can continue to grow and evolve just like the WordPress block directory.

Source :