Block API

[gziolo]

This overview issue collects an actionable list of impactful tasks that capture possible enhancements to the various Block APIs that exist to power the WordPress block editor.

Block API is intentionally a vague term reflected in the list of action items grouped into categories like block registration, block attributes, block interactions, block modification, etc. What’s in common is that the tasks included aim to resolve the most common friction points or increase the potential of the APIs offered for WordPress block, plugin, and theme authors. In effect, it makes it possible to fulfill the needs of developers wanting to adopt the block editor in their projects.

🛠️ = in development
🤚 = needs to be unblocked

❗Top Things

High-impact projects in active development:

• 🛠️ HTML API: Plans for 6.8 #63037
• 🛠️ Stabilize Typography Block Supports Keys for WP 6.8 #63001
• 🛠️ Stabilize Border Block Support Keys for WP 6.8 #64312

📖 Backlog

Planned tasks that are being actively researched, waiting for developers to pick them up or on hold until they get unblocked.

Block Registration

• 🤚Explore a mechanism improving developer experience to use one API (example: useBlockProps, InnerBlocks) that run different code depending on the context: edit, save, or frontend (Blocks: Add block environment and directives support (edit vs save) #48590).
• Add SlotFill for the block's description in the sidebar to allow custom code (Block Registration: add SlotFill to extend a block's description #49887, Query: Fix add new post link position via private SlotFill #49819). At the moment we use block's description which is a simple string. However, it would be sometimes useful to include some custom HTML code like <a />.
• Start using REST API for block types in WordPress core (Replace unstable__bootstrapServerSideBlockDefinitions with call to block type REST API #22812).
• Register multiple blocks from several block.json files. At the moment developers have to register every block separately. It could help to update register_block_type or add new register_block_types on the server to support auto-discovery of multiple blocks through block.json in a given target folder.
• "Universal blocks" that could be written once and run in both PHP and JS with the help of a compiler (Universal blocks and block hydration #38224).
• Allow custom path for languages to be defined in block.json for translations used with JavaScript (Trac #54797).
• Explore advanced options on the intersection of ancestor and parent to support allow/deny lists based on the editor, post-type, and template type context (Block registration: offer option to register a block only in a specific editor #46900, Allow/deny block use based on post-type or template context #41062, related discussion starts also in Post Comments Loop: Unable to put comment blocks inside rows or columns #37181 (comment)).
• Add a warning for block developers if they use reserved words for attribute names (Blocks: Add a warning for developers if they use reserved words for attributes #48112).
• Validate each arg before setting WP_Block_Type properties (Validate each arg before setting WP_Block_Type properties #48039).
• Automatically set reusable to false when a block has a parent defined #35223

Block Assets

Block assets are JavaScript (editorScript, script, viewScript) and CSS (editorStyle, style) defined in block.json file.

• 🤚 Block and Component Lazy Loading #2768
• 🛠️ Allow customizations for assets in block.json as explained in Trac #54018 and to fix Blocks without asset.php file cannot be registered #40447. Tracked in Blocks: Allow customizations for assets in block.json #46954.
• Add new utility function to add script / viewScript to an already registered block (Blocks: Add new utility function to add script / viewScript to an already registered block #48382).
• Iterate on absorbing block styles (currently __experimentalStyle in block.json) as part of the global styles mechanism (Iterate on absorbing block styles as part of the global styles mechanism #45198).
• WPDefinedAsset doesn't implemented for CSS files referenced in block.json #56838

Block Attributes

• 🤚 Solving some semi-related shortcomings with block attributes (Solving some semi-related shortcomings with block attributes #49466).
• 🛠️ Add support for sourced attributes on the server (HTML API: Add attribute sourcing wordpress-develop#6388).
• Optional support that optimized blocks for usage as structured data (Blocks: Optional support that optimizes handling blocks for usage as structured data #49437).
• Explore how to connect an individual block attribute with a given UI control and the save flow. In effect, have a simple way to allow editing block attributes without manually writing all code for block controls and inspector controls (Blocks: Attritibutes should auto generate form #48245).
• Exploring how Patterns can be connected to Schemas (Exploring how Patterns can be connected to Schemas #41606).
• Explore adding media related roles to block attributes #65186
• Blocks: "enum" without "type" in block.json throws notices and warnings in PHP #57942
• Parsing "data-*" attributes #59532

Block Supports

• 🤚Allow controlling behaviors/interactions by blocks and themes (Outline for Block Behaviors #50029).
• Ensure that the block editor respects parent, ancestor, and supports.multiple when using drag & drop, or copy & paste (Restrict copy/paste of a block in the editor when supports.multiple = false and supports.removal = false #53471).
• Add the ability to limit the number of items within an Inner Blocks area (Add ability to limit the number of items within an Inner Blocks area #42342).
• Block Hooks: Respect allowedBlocks field and control for users #53989

Block Variations

• Add handling for block type name aliases used with block variations (Blocks: Add support for block name aliases for variations #43743). They should fall back if necessary to the original block type name, e.g. woocommerce/product-list that can get resolved to the product-list variation added to the core/query block.
• Add support for the ancestor and parent settings for the block variation (Blocks: Add support for the ancestor and parent settings for the block variation #48424).
• Allow users to select multiple block style variations (Blocks: Allow users to select multiple block style variations #14598).
• Allow block styles scoped to variations (Block style for specific block variation #40621).
• Add PHP version of wp.blocks.registerBlockVariation (Block Variations: Add PHP version of wp.blocks.registerBlockVariation #47170).
• Add support for allowedBlocks attribute in block variations #65851

Content Modelling

• 🛠️ HTML API: Roadmap #60397
• 🛠️ Tracking issue: Block bindings API #60954
• Offer the ability to inject and manipulate inline dynamic tokens for blocks using Rich Text (How to use dynamic data with registerFormatType #18490 and Inline Dynamic Content Solutions #21932).
• Dynamic replacement of server-provided content in blocks and in HTML attributes (Bits: Dynamic replacement of server-provided content (tokens, "shortcodes 2.0") #39831).
• Block Bindings: Expose bindable attributes through an annotation in the block definition #64756
• Open up "Pattern Overrides" and therefore intern block bindings to custom dynamic blocks #64870

Various

• Offer a way to define the list of disallowed blocks to mitigate the limitation of the currently supported allowed list (Lack of configuration endangers editorial workflow #49592, Block directory doesn't work when blocks are hidden #38500).
• Features like pattern overrides and block bindings have limited control over block UI #58233
• Block API: Introduce abstraction for better management of inspector controls  #62439
• Allow to disable settings for specific blocks #38767
• 🤚Introduce classification of block validation types to make block deprecation handling more flexible (Classification of block validation types #21703).
• Introducing more robust permission handling across the various capabilities (block registration, locking, etc) so administrators can define what blocks are available for different user roles (or even what capabilities of individual blocks are to be exposed). See more in Phase 3: Collaboration, Block Library.
  • Block Editor: Provide a way to customize items in Block Toolbar #47641.
  • Block Editor: Provide a way to customize panels in Inspector Controls #33891.
• Proper server-side APIs for block modification (Proper server-side APIs for block modification #6494)
• Expose parsed block data directly through REST API endpoints (Trac#53603, POC Add block data to REST API #2649)
• Expand get_posts $filter parameter to allow a blocks as a return shape (Trac#53602)
• Correctly pass parent block context in REST API call for Server-side Render Component (Pass parent block context during server side rendering #40714).
• Make block style slug available to render callback #56278
• Find a way to cover multiblock plugins where you have all of them installed but they wouldn’t get activated until you insert them for the first time. It’s mostly a UX challenge because you could show them in the inserter like blocks from the Block Directory, but they could get higher priority.
• Better UX to prevent nesting some blocks into self that crashes the editor (the same Reusable Block, Template Part, Post Content, etc).
• "Undo trap": Avoid getting stuck in an editing state ("Undo trap": Avoid getting stuck in an editing state #8119).
• Blocks with different versions like Log In/Out block, or different state like Navigation blocks. Explore how to build UI that allows full page control over global states like the user session, or viewport. Feed that information into the block context so users can edit and preview blocks in different contexts (Blocks: States #57719, see also related discussion How should we handle different layers/states for the same block in the editor? #38108).
• Refactor the block parser to work asynchronously (Block API: Refactor the parser module in preparation for further work #15674).

Developer Experience

• Add multiple styles/scripts with dependencies, version, etc. in block.json and provide examples in documentation #53847
• Docs: Create a section about Block Hooks in the Block Editor Handbook #63906
• Docs: Create a section about Block Bindings in the Block Editor Handbook #63026
• Document role attribute property  #65614
• Documentation: Clarify the behavior of parent when empty during block registration #15731
• Documentation: spacing.blockGap explanation is inadequate for custom blocks #43921
• Scaffold for typescript in @wordpress/create-block #39915

[luisherranz]

Develop strategies for loading JavaScript on the frontend - head vs footer, but also frontend hydration techniques explored in Implement different hydration techniques block-hydration-experiments#12.

This can be a good first step, but acknowledging that we need more than that in the near future: probably asycn/defer (something like what @adamsilverstein proposed in WordPress/performance#168) or even do the jump to ESM.

Apart from that, I think we should explore a mechanism to export different code depending on the context (Edit, Save, or Frontend): WordPress/block-interactivity-experiments#11

[gziolo]

Thank you @luisherranz for your feedback. I included your suggestions together with references.

I also added two more items that I missed initially but have been following closely for a long time:

• Introduce classification of block validation types to make block deprecation handling more flexible (Classification of block validation types #21703).
• "Universal blocks" that could be written once and run in both PHP and JS with the help of a compiler (Universal blocks and block hydration #38224).

[fabiankaegy]

@gziolo I have reviewed the items that are already tracked here and I myself have created 3 issues recently that I think could all be added:

• Add option to block API to only allow root level insertion #42548 (the one you added the comment to)
• Add ability to limit the number of items within an Inner Blocks area #42342
• Add ability to restrict block to only be used once within inner blocks area #38958

[gziolo]

☑️ Completed in WordPress 6.1 cycle

Block Registration

• Reference PHP file necessary for the block from block.json. It could be a new setting render in block.json (Trac#53148, Blocks: Add new render property in block.json for block types wordpress-develop#3222, Blocks: Add new render field to block.json #42430).
• Better imports for core blocks in the Gutenberg repository and @wordpress/block-library to make it easier to consume individual blocks (Block Library: Make it possible to import individual blocks #42258).
• Combine block metadata during the build process into one file to avoid loading too many block.json files for core blocks (see Improve block loading PHP performance wordpress-develop#2252).

Block Assets

Some of the details were tracked in #33542.

• Add multiple assets per type (editorScript, script) to bring complete consistency to what we already have for styles (Blocks: Allow registering multiple items for all supported asset types wordpress-develop#3108).
• Change the default behavior for viewScript when the render_callback is present in the block definition (Trac#56470).
• Allow plugins to modify a theme.json file in a similar way themes do (Allow plugins to include a theme.json file in the same way themes do #41707).

Documentation

• Cover optional block variations usage in block.json (Update help docs and schema file with block variations #40490, Docs: Add variations key to block.json JSON schema definition #42539).

[gziolo]

Update

Completed during WP 6.4

• Include Block Hooks in WordPress 6.4 #53987

Added

• Epic: Block Hooks Features for WP 6.5 #54904 (Top Things)
• Automatically set reusable to false when a block has a parent defined #35223

Needs review

• Introduce viewStyle for styles used only on the front end to align with scripts and viewScript (Block API: Add viewStyle property support to block.json #55492, Add viewStyle property for block metadata wordpress-develop#5531).

[gziolo]

Update

Completed during WordPress 6.5 cycle

• Connecting block attributes and custom fields & Block Bindings API for WP 6.5 #53300
• Epic: Interactivity API - public 1.0 version #56803
• Epic: Block Hooks Features for WP 6.5 #54904
• Pattern Overrides epic (WordPress 6.5) #53705
• HTML API: Plans for 6.5 #54579
• Create a system for inserting site/post metadata into generic blocks (Create a system for inserting site/post metadata into generic blocks #37753.
• Provide a general solution to customize the list of allowed blocks for inner blocks with block attributes (Blocks: Provide a general solution to customize the list of allowed blocks for inner blocks with block attributes #15682, Define allowed inner blocks in register of block type #16560, Not possible to change allowedBlocks dynamically #14515).
• Start using JavaScript Modules and Import Maps (Start using JavaScript Modules and Import Maps #36716).
• Support for deferred block variation initialization on the server has been added, which improves performance (https://core.trac.wordpress.org/ticket/59969).
• Introduce view style for styles used only on the front end to align with scripts and view script (block.json: Add viewStyle for frontend-only block styles #54491, https://core.trac.wordpress.org/ticket/59673).
• Asset registration file .asset.php has been made optional for blocks (https://core.trac.wordpress.org/ticket/60460).
• Add a new "Create a block tutorial" #56305

New

• 🔝 Block Bindings: Iteration for WP 6.6 #60956
• 🔝 Introduce overrides in synced patterns iteration for WP 6.6 #59819
• 🔝 Interactivity API: Iteration for WP 6.6 #60219
• 🔝 HTML API: Plans for WP 6.6 #60324
• 🔝 Block Hooks: Iteration for WP 6.6 #60252
• WPDefinedAsset doesn't implemented for CSS files referenced in block.json #56838
• Features like pattern overrides and block bindings have limited control over block UI #58233

Resources

• Dev note: Interactivity API
  • An introduction to block-based mega menus
• Dev note: The Block Bindings API.
  • Introducing Block Bindings, part 1: connecting custom fields.
  • Introducing Block Bindings, part 2: Working with custom binding sources.
• Dev note: Updates to the HTML API
• Dev note: Updates to Block Hooks
• Dev note: Script Modules in 6.5
• Dev note: Performance improvements for registering block type variations with callbacks
  • How to register block variations with PHP
• Tutorial: Build your first block

[gziolo]

Update

Completed during WordPress 6.6 cycle

• Block Bindings: Iteration for WP 6.6 #60956
• Introduce overrides in synced patterns iteration for WP 6.6 #59819
• Interactivity API: Iteration for WP 6.6 #60219
• HTML API: Plans for WP 6.6 #60324
• Block Hooks: Iteration for WP 6.6 #60252
• Block Variations: Support dot notation in isActive string array #62088

Completed during WordPress 6.7 cycle

• Block Bindings iteration for WordPress 6.7 #63018
• HTML API: Plans for 6.7 #60396
• Interactivity API iteration for WordPress 6.7 #63232
• Default block alignment class is not in get_block_wrapper_attributes #50027
• Default attributes for block-support properties don't apply on dynamic blocks #50229
• Docs: Add register_block_type_args as a way to filter registration of a block in the documentation #54112
• block.json: Allow passing filename as variations field #62092
• Blocks: Stabilise role attribute property #65484
• Extend Block Metadata PHP Cache to Third-Party Blocks wordpress-develop#7303
• Block Hooks: Respect "multiple": false wordpress-develop#7443

New

• HTML API: Plans for 6.8 #63037
• Stabilize Typography Block Supports Keys for WP 6.8 #63001
• Stabilize Border Block Support Keys for WP 6.8 #64312

Resources

• Editing custom fields from connected blocks
• Updates to the HTML API in 6.6
• Updates to the Interactivity API in 6.6
• Improvements to active block variation detection
• Block Bindings: Improvements to the Editor Experience in 6.7
• Updates to Block Hooks in WordPress 6.7
• New block type registration APIs to improve performance in WordPress 6.7