Block Directory in WP-Admin: V1

This is an update to the #block-directory project. You can see the first round of concepts and feedback in this previous post. Feedback from that post was used to update the mockups in this round of iterations.

See all mockups in Figma


Building the new BlockBlock Block is the abstract term used to describe units of markup that, composed together, form the content or layout of a webpage using the WordPress editor. The idea combines concepts of what in the past may have achieved with shortcodes, custom HTML, and embed discovery into a single consistent API and user experience. Directory in wp-admin presents us with a couple opportunities to redesign certain existing patterns, and turn them into reusable components. When we revisit future admin pages, we’ll have these components available to replace the older patterns.

Here’s some updated patterns we can turn into components for this project.

Page Headers

There are tons of pages in the WordPress admin. None of them are consistent.

I’d previously explored a consistent headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. for admin pages, but it still felt subpar:

When I started working on the Block Directory, I wanted to take another stab at a header that could work across the entire admin. These were roughly based off of Material’s headers, then adjusted and improved to fit our use cases.

Page headers consist of the following elements:

  • The page title.
  • A short description of what this page is and what it’s for, ideally only a sentence or two long.
  • Action buttons on the left (add new, upload, etc.).
  • MetaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. buttons on the right (help, settings).

Rather that opening Help and Screen Options (now “Settings”) in tabs, we can use the modal component:

This is a more portable approach than the existing pull-down tabs, and also makes the longform help content much easier to read, since the modal constrains it to a much better line-length for readability.

Note: the modal header and panels don’t line up in the mockups due to some conflicts in the Figma files, but should in real life.

List Tables

Y’all, List Tables are as old as dirt. They’ve done a good job for the past decade and whatever, but they could use some modernization. Lists Tables would be a way to bring all of the list actions together into one single container, rather than floating above and below, disconnected from the table. I’ve kept the table items themselves the same, but made adjustments to the header, footer, and external table elements.

List Tables are composed of the following elements:

  • A table heading with optional bulk select checkboxes.
  • Rows, same as the existing list table pattern.
  • A table footer that instead of repeating the header, has meta information (# of pages, previous/next navigation). When items are selected, bulk actions take the place of the navigation:

This is similar to how we handle bulk deletion in the Media admin screen.

Empty States

There isn’t currently a consistent “Empty” State for admin pages (like when you don’t have any posts, pages, comments, etc.). This new component take a stab at one we can reuse for all pages in the future.

Empty States are composed of three elements:

  • A “not found” graphic.
  • Text stating there are no items.
  • An action, like a button, to help resolve that there are no items.

You can see more component documentation for the Block Library in Figma.

Next Steps

Per this 2019 projects recap, the Block Directory is slated for inclusion in WordPress 5.5. Development will hopefully start soon.

In the meantime, if you have a block you’d already like to include in the directory, you can already submit it! Check out this post on Meta for more information.

Thanks to @tinkerbelly for taking my sloppy mocks and making all my one-off elements into reusable Figma components!