I'm trying to tranform legacy widgets to block, I was reading the docs, but I couldn't understand where to put this javascript code :

transforms: {
from: [
        type: 'block',
        blocks: [ 'core/legacy-widget' ],
        isMatch: ( { idBase, instance } ) => {
            if ( ! instance?.raw ) {
                // Can't transform if raw instance is not shown in REST API.
                return false;
            return idBase === 'example_widget';
        transform: ( { instance } ) => {
            return createBlock( 'example/block', {
                name: instance.raw.name,
            } );

it says that I should add this javascript to my block's definition. where is that?

wordpress docs: https://developer.wordpress.org/block-editor/how-to-guides/widgets/legacy-widget-block/

  • did you create a block to replace the legacy widget? This is a block transform definition, if you didn't create a new block to convert your legacy widget into then what you want isn't possible. This isn't an option you can add to a legacy widget or a compatibility layer, it's a migration route to a brand new block that replaces the old widget
    – Tom J Nowell
    Commented Oct 5, 2021 at 9:03
  • You mean I have to to create a new block for scratch that replaces the legacy widget. So this whole transformation just not to break the website or what?
    – shadi
    Commented Oct 6, 2021 at 13:13
  • The legacy widget is a block already, it's a block that loads a widget and displays it, you don't need to do any of this unless you create a brand new block that replaces your widget. The code you shared is the transform that lets you migrate your widget content to the new block when you do that. You would do this if you wanted to replace your widget with something that's usable outside of widget areas
    – Tom J Nowell
    Commented Oct 6, 2021 at 17:54
  • if the goal is to just preserve the status quo then no changes or code is necessary, which is obvious when you update and use the new widgets area interface, existing widgets can still be added, they just show up as legacy widget blocks in the UI. It's possible this block might go away in 30 to 40 years when, and if it did then pulling it out into a plugin would be trivial. WP is big on backwards compatibility and breaking changes are rare, Widgets completely disappearing and needing to be rebuilt from scratch on all sites has not happened, and would be considered a major bug by the core team
    – Tom J Nowell
    Commented Oct 6, 2021 at 17:56

1 Answer 1


TLDR: If you wanted to update to v5.8 you don't need to do anything to make widgets work, they won't break if you update. There is no conversion step, no updating of code to make it work. migration is not necessary.

I'm trying to tranform legacy widgets to block, I was reading the docs, but I couldn't understand where to put this javascript code :

If you decide that you want to port your WP_Widget widgets so that they can be used outside of widget areas, then this is the mechanism that lets you transform your old widgets into the new block you create. So it goes inside the new blocks transform section when you register it.

If you do not have a new replacement block though, then no changes are needed to continue using widgets as widgets. Anybody who has updated to 5.8 and opened the new widgets UI will see their widgets are still there, and can be added and changed. This is because the core developers added a compatibility layer so that widgets show up as legacy widget blocks.

If you did decide to create a replacement, perhaps because you plan to use full site editing or want to embed it inside posts, here are some pointers:

  • use server rendered blocks so you can port your widget rendering code directly
  • your widgets options should be ported directly to block attributes
  • you'll need an edit component to replace your widgets form, this is probably going to require some javascript. The edit component is what the editor displays.
  • the save component is what generates the HTML that goes in the database, but if you're rendering the HTML in PHP like I recommended, set this to null or don't specify a save component at all. The block editor will assume you plan to use PHP for it
  • there's a server render component, pass it the block type and the attributes and it will call the server and run your blocks PHP so you can display/preview it in the editor

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.