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.
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.
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 WordPress.org 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 Purpose of WordPress Block Directory
The new WordPress block directory is separate from the main WordPress.org plugin directory, so you’re either browsing regular WordPress plugins or single block plugins.
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.
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.
|Audio||Embed a simple audio player.|
|Buttons||Drive conversions with beautiful buttons.|
|Categories||Display a list of all categories.|
|Classic||Use the classic WordPress editor|
|Code||Display code snippets that respect your spacing and tabs.|
|Columns||Add a block that displays content in multiple columns, then add whatever content blocks you’d like.|
|Cover||Add an image or video with a text overlay – great for headers.|
|Embed||Embed videos, images, tweets, audio, and other content from external sources.|
|File||Add a link to a downloadable file.|
|Gallery||Display multiple images in a rich gallery.|
|Heading||Introduce new sections and organize content to help visitors (and search engines) understand the structure of your content.|
|Image||Insert an image to make a visual statement.|
|Latest post||Display a list of your most recent posts.|
|List||Create a bulleted or numbered list.|
|Paragraph||The building block of all narrative.|
|Pull quote||Give special visual interest to a quote from your text.|
|Quote||Give quoted text visual emphasis.|
|More||Adds a “Read more” element|
|Separator||Create a break between ideas or sections with a horizontal separator.|
|Shortcode||Insert additional custom elements with WordPress shortcodes.|
|Spacer||Add 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.
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.
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.
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.”
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 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:
TWST is a simple, yet genius single-block plugin that allows you to insert a login form anywhere on a post or page.
How To Install New WordPress Blocks
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
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.
With everything in place, your website can continue to grow and evolve just like the WordPress block directory.
Kristen has been writing tutorials to help WordPress users since 2011. You can usually find her working on new articles for the iThemes blog or developing resources for #WPprosper. Outside of work, Kristen enjoys journaling (she’s written two books!), hiking and camping, cooking, and daily adventures with her family, hoping to live a more present life.