@wordpress/block-library

Block library

Block library for the WordPress editor.

Installation

Install the module

npm install @wordpress/block-library --save

This package assumes that your code will run in an ES2015+ environment. If you're using an environment that has limited or no support for such language features and APIs, you should include the polyfill shipped in @wordpress/babel-preset-default in your code.

Building JavaScript for the browser

If a view.js file (or a file prefixed with view, e.g. view-example.js) is present in the block's directory, this file will be built along other assets, making it available to load from the browser.

This enables us to, for instance, load this file when the block is present on the page in two ways:

1. Using the block's render_callback:

function render_block_my_block() {
	$script_path = __DIR__ . '/my-block/view.js';

 	if ( file_exists( $script_path ) ) {
 		wp_enqueue_script(
 			'wp-block-my-block-view',
 			plugins_url( 'view.js', $script_path ),
 			array(),
 			false,
 			true
 		);
 	}
}

function register_block_my_block() {
	register_block_type(
		__DIR__ . '/my-block',
		array(
			'render_callback' => 'render_block_my_block',
		)
	);
}


add_action( 'init', 'register_block_my_block' );

1. Using the render_block filter:

function render_block_my_block() {
	$script_path = __DIR__ . '/my-block/view.js';

 	if ( file_exists( $script_path ) ) {
 		wp_enqueue_script(
 			'wp-block-my-block-view',
 			plugins_url( 'view.js', $script_path ),
 			array(),
 			false,
 			true
 		);
 	}
}

apply_filter( 'render_block', 'render_block_my_block' );

API

registerCoreBlocks

Function to register core blocks provided by the block editor.

Usage

import { registerCoreBlocks } from '@wordpress/block-library';

registerCoreBlocks();

Parameters

• blocks Array: An optional array of the core blocks being registered.

Contributing to this package

This is an individual package that's part of the Gutenberg project. The project is organized as a monorepo. It's made up of multiple self-contained software packages, each with a specific purpose. The packages in this monorepo are published to npm and used by WordPress as well as other software projects.

To find out more about contributing to this package or Gutenberg as a whole, please read the project's main contributor guide.

Adding new blocks

⚠️ Adding new blocks to this package requires additional steps!

1. Do not forget to register your new block in the index.js file of this package. For example, if you were to add a new core block called core/blinking-paragraph, you would have to add something like:

   // packages/block-library/src/index.js
   import * as blinkingParagraph from './blinking-paragraph';
   
   // Then add `blinkingParagraph` to either `__experimentalGetCoreBlocks()`
   // or `__experimentalRegisterExperimentalCoreBlocks()`
   

2. Register your block in the gutenberg_reregister_core_block_types() function of the lib/blocks.php file. Add it to the block_folders array if it's a static block or to the block_names array if it's a dynamic block.