Solvedgutenberg Block Transforms should be more discoverable/obvious

I was writing a block, added a line of text I wanted to convert to a heading, and couldn't work out how to convert it to a heading.

I think this is a discoverability/ usability issue. I eventually found it in the toolbar, but it was not obvious. There's no indicator showing clicking the option will offer more options. Something as simple as a small down arrow next to the block type icon would have helped considerably.

I am used to typing and then changing the styling the content after the fact. I don't want to have to leave my flow to add a header/ whatever. But finding the transforms took much longer than it should have, and I was swearing to myself since I know it used to be available but wasn't in any of the places I remembered.

42 Answers

✔️Accepted Answer

I'd like to propose an alternative as I think there is already an over-reliance on iconography in Gutenberg. Icons like gears and dots hide much of the editor's functionality behind ambiguous glyphs that can only be learned through experimentation. This is tolerable for advanced or little-used functionality, but something as simple as transforming text should be one of the clearest functions in the editor. We don't need to invent a new icon to make transforming text at least as obvious as it is in word processing apps like Word, Pages, or Google Docs with which new users will be familiar.

I saw that @jasmussen already reverted the paragraph icon back to its more traditional form (the pilcrow) in the latest master branch. This is an improvement, but I think we can do more. Below is a proposal to clarify the block transformation workflow through a text-based control already familiar to users. I've left the actual behavior of the block selection untouched while hopefully improving discoverability.


The proposed control offers the following improvements:

  • Clarity - Text reduces ambiguity, especially in unconventional icons like Preformatted or Verse.
  • Contrast - The control is obviously different than its neighbors and won't be confused with alignment.
  • Affordance - The dropdown arrow suggests a menu reveal, which is what happens when it is selected.
  • Freedom - We can design the block icons based on clarity and not worry about their proximity to related icons in the toolbar. For example, H is the obvious icon to represent a heading, but it appears to have been changed to T just so that it wouldn't blend in with the H2/H3/H4 icons next to it. With the proposed control, that's not a problem.
  • Familiarity - WP users know this control from the TinyMCE editor or have used a similar control in other word processors.

Familiarity with one of the most important functions of an editor is a good thing. In the midst of a paradigm shift like Gutenberg, conventions can ease the transition, especially for such a common user action like text transforms.

Other Answers:

Just wanted to say thanks for all the constructive voices here and willingness to find better solutions. If there's anything that is fairly clear is that the current "block switching" interaction is not as obvious as it could be.

I think using the paragraph icon instead of the one that is easily confused as aligment, @jasmussen's update in #9310, plus the addition of the drop-down arrow are a good baseline to check on the next release and see if we need something more involved. @kevinwhoffman it'd be great to expand on your proposal and see how it might look across more blocks and nested contexts.

I note that I was working on an iPad when I was finding it difficult. This should be an interface that does not depend on hover. It should be discoverable on touch-only devices too!

Hi @kevinwhoffman, nice mockups, thanks for joining us in the fray!

Back in the day we explored something similar, to figure out the pros and cons to each approach:


There are many aspects to consider, though

  • The need for the editor to be responsive (see also #7479 (comment))
  • The need for the block toolbar to scale to editors with thin main columns through editor styles, as well as nested contexts (see also #9075)
  • The need to make transforms plug-in friendly. For example you can't only transform paragraphs, headings, quotes and text blocks. You can transform a heading to a cover image. You can select multiple images and transform to a gallery. One goal is to allow a plugin to register itself as a compatible transform, for example a ToDo list block might register itself as compatible with the List block.
  • Because we dock the toolbar to the block so as to be contextual, it essentially covers preceeding text. Although there is an option to fix the toolbar to the top of the screen, this is something to be mindful of when making the toolbar wider.
  • The need to accommodate very long block names including translations.
  • Accessibility — we have 13px as the minimum font size.

One of the kickoff goals of this editor project was to unify multiple disparate interfaces into one. Instead of you having to learn how to use widgets, shortcodes, oembeds, custom HTML and TinyMCE in order to accomplish a rich layout, we wanted you to only have to learn a single interface, and once you knew that, you could do anything. This has been the driving force behind unifying everything under the block metaphor. You may have to learn how to use the block, but once you know it, you know all of WordPress.

It's all a delicate balancing act, but we're definitely open to finding solutions that thread the needle!

As I shared over on #9228 I wonder if a simple dropdown indicator is enough here?


It doesn't indicate the specific purpose of the icon, but it does promote discoverability.

Related Issues:

gutenberg Can't NPM Install: ENOENT: no such file or directory .staging/core-js-c2a9e69c (solved with rm -rf node_modules && npm install)
Delete package-lock.json and run npm install Hey @mintplugins which version of node and npm do you u...
gutenberg What is the proposed way to update blocks?
I am facing the same issue and absolutely agree with Fabian on this What if the frontend switches to...
gutenberg Are iframes a viable long-term solution for meta boxes?
Do all metaboxes have to work on mobile? Yes why wouldn't they? What are the cases (if any) that wou...
gutenberg Supporting Metaboxes
I also want to emphasize that many plugins use custom post types that rely on meta boxes without a c...
gutenberg Block API: Server-side awareness of block types
@aduth thanks for creating this ticket and CCing me! there is still a lack of general understanding ...
gutenberg Immediate crash of editor upon opening new post page (solved by updating nginx config)
Fixed tldr: if you run Nginx you might need to update your nginx config I have the same problem With...
gutenberg Gutenberg breaks completely if site URL is not the same as wordpress URL
Here's what I did to make it work (I only have 1 site): Issue Overview I have wordpress installed on...
gutenberg The editor has encountered an unexpected error. (solved by updating the try_files nginx configuration)
Just to confirm the following worked for me: try_files $uri $uri/ /index.php$is_args$args; @Zenexer ...
gutenberg Block Transforms should be more discoverable/obvious
I'd like to propose an alternative as I think there is already an over-reliance on iconography in Gu...
gutenberg Can't style embedded videos properly due to inline width & height
Here's basic front-end css: You are welcome. Describe the bug There's numerous issues open that disc...
gutenberg Is it possible to disable default block styles?
Removing works fine for me with the following example: This script is enqueued via wp_enqueue_script...
gutenberg Introduce concept of block templates for full site editing
Since we already did some Full Site Editing work on I’ll try to convey some of the thi...
gutenberg Allow multiple InnerBlocks per block
Imagine something simple as this example... Currently InnerBlocks can only be rendered once into any...
gutenberg Event or callback after block loaded on editor
I was also looking for the same options but could not find any solutions anywhere It seems like no e...
gutenberg @wordpress/env: A zero-config, self contained local WordPress environment for development and testing.
We've iterated a lot on @wordpress/env these past few weeks and I think we're now at the point where...
gutenberg Classic + Custom HTML blocks: Convert to Blocks removes valid inline formatting
@ZebulanStanphill @danielbachhuber F.Y.I I tried some fix phrasingContentReducer for ruby tag Now it...
gutenberg Metaboxes overlap Gutenberg in Chrome 77
Confirmed that the CSS solution worked for us I dropped this into our theme, ~~ Added by @nerrad ~~ ...
gutenberg Improve behaviour when saving content while offline
It would indeed be a great improvement to show a warning when offline and to store the changes in lo...
gutenberg How to replace the Document Settings panels or controls?
@jonathanstegall The removeEditorPanel() method only supports the removal of 5 built-in meta boxes: ...
gutenberg Support for Responsive Columns
Just adding my 2 cents.. In my own theme I simply add a media query and then set each column (.wp-bl...
gutenberg How to add blocks is not obvious enough and only getting worse.
Please I'm submitting this issue because I think that issue #5074 doesn't quite go far enough in out...
gutenberg My Parent Pages Are Still Missing In Gutenberg
I started work on implementing an accessible-autocomplete for sites with a large number of pages in ...
gutenberg How to server render block with nested blocks?
Hey sorry all for the delay but it is possible to have an InnerBlocks and render your block on the s...
gutenberg Dynamic reusable blocks: technical details
I might be missing a piece of this puzzle so apologies for wading into this late! The above REST spe...
ddev In WSL2 ddev start fails at docker-credential-desktop.exe, "error listing credentials"
I had to set credsStore: in my ~/.docker/config.json .. it was previously set to credentials.exe ...
woocommerce The Header Mini Cart does not update after a product is removed
Here is my fix EXPLANATION OF THE ISSUE After removing a product on the Shopping cart page /cart/ ...
FoundationPress Missing modules when running npm run build or npm install
The error in the original post is from running npm run build Hi I am working on a foundation press p...
woocommerce Rethinking 3.6's Dashboard Ads (#22857 )
​It appears what you're doing here is tracking usage reporting that back to your API and returning t...
FoundationPress After Node update, Issue running npm run production
Try this: npm uninstall gulp --save Then once that is complete run: npm install then: npm run build ...
lando Unhandled rejection Error: problem parsing null.tooling.cache. Ensure it is valid JSON!
Hi I had the same issue just now and apparently I only missed adding the name on my .lando.yml file ...
wp graphql Get Single Nodes (posts, terms, users, etc) by more than ID
The next release I'm working on (#1086) addresses this (the ability to fetch single nodes by various...
lando lando does not start
On ubuntu 16.04 docker rm landoproxyhyperion5000gandalfedition_proxy_1 helped me to ged rid of this ...
sage Sage 9.0.10 - postcss.config.js not working
To anyone else hung up on this I found a workaround My version of this issue was not font related bu...
woocommerce Negative amount as fee and tax calculation in checkout
If someone is still looking for an answer here is mine It works like a charm Describe the bug I have...
wp calypso Editor: Permission Errors when trying to Update/Publish Post/Pages
The fix has been deployed today to wpcom as D57128 after the first attempt had to be reverted due to...
lando Permissions issue with Docker
I also ran into this on: macOS 11.1 (Big Sur) Lando v3.0.25 I fixed with sudo chown -R username /Use...
acf to rest api How to get ACF post object field with ACF fields
Hi @travis-zookacreative Thanks for using my plugin bellow I wrote an example most generic V3 V2 Fun...
lando Unable to 'lando pull' pantheon site
This worked for me: lando terminus auth:login --machine-token=ABCDEFGHIJKLMNOPQRSTUVQXYZ (don't stea...
lando Please add Docs for Drupal's "Drush" CLI Command Debugging via XDebug
This is what worked for me: Then turning on Listen for PHP Debug Connections in PHPStorm and calling...
lando mysql stop connecting after lando restart
I think I found a solution I had same issue multiple times and I was forced to completely uninstall ...
woocommerce Attributes lost all parents
Hi @ABCPortugal like Claudio wrote you need to use the filter woocommerce_taxonomy_args_{$name} for ...
lando Support Xdebug 3
This worked for me PHPStorm 2020.3 drupal9 Xdebug 3 is out and comes with a lot of performance optim...
wp graphql How to create query/mutation for custom table in WP
WPGraphQL can work with any data source It's optimized to work with WordPress core data (Posts Terms...
woocommerce PayPal Intermittent Transaction cancelled or Internal server error on guest checkout
Thanks @mikejolley EXPLANATION OF THE ISSUE Using WooCommerce 3.0.5 and guest checkout ...
woocommerce product slider not working for rtl on woocommerce update
all you need to do is just set direction for gallery wrapper to rtl EXPLANATION OF THE ISSUE I updat...
jetpack Jetpack JSON API access crashes PHP-FPM running PHP 7.1
The Jetpack people noticed me about the freshly baked 5.3 update today:
acf to rest api Apply same post format as WP JSON if ACF return format is Post Object
Allright thanks! The ticket on core is picked up and it will be fixed in WP 4.9.5 For the people who...
ddev Create a service configuration for varnish
Hi this is how we are doing this at wegewerk: What happened (or feature request): Edit: @stborchert ...
wp calypso Calypso: Deep links redirecting
This is a real bug and it's probably been around for some time Not a recent regression ...