Title: register_block_style_handle
Published: August 11, 2020
Last modified: May 20, 2026

---

# register_block_style_handle( array $metadata, string $field_name, int $index ): string|false

## In this article

 * [Parameters](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#source)
 * [Related](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#related)
 * [Changelog](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#changelog)

[ Back to top](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#wp--skip-link--target)

Finds a style handle for the block metadata field. It detects when a path to file
was provided and registers the style under automatically generated handle name. 
It returns unprocessed style handle otherwise.

## 󠀁[Parameters](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#parameters)󠁿

 `$metadata`arrayrequired

Block metadata.

`$field_name`stringrequired

Field name to pick from metadata.

`$index`intoptional

Index of the style to register when multiple items passed.
 Default 0.

## 󠀁[Return](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#return)󠁿

 string|false Style handle provided directly or created through style’s registration,
or false on failure.

## 󠀁[Source](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#source)󠁿

    ```php
    function register_block_style_handle( $metadata, $field_name, $index = 0 ) {
    	if ( empty( $metadata[ $field_name ] ) ) {
    		return false;
    	}

    	$style_handle = $metadata[ $field_name ];
    	if ( is_array( $style_handle ) ) {
    		if ( empty( $style_handle[ $index ] ) ) {
    			return false;
    		}
    		$style_handle = $style_handle[ $index ];
    	}

    	$style_handle_name = generate_block_asset_handle( $metadata['name'], $field_name, $index );
    	// If the style handle is already registered, skip re-registering.
    	if ( wp_style_is( $style_handle_name, 'registered' ) ) {
    		return $style_handle_name;
    	}

    	static $wpinc_path_norm = '';
    	if ( ! $wpinc_path_norm ) {
    		$wpinc_path_norm = wp_normalize_path( realpath( ABSPATH . WPINC ) );
    	}

    	$is_core_block = isset( $metadata['file'] ) && str_starts_with( $metadata['file'], $wpinc_path_norm );
    	// Skip registering individual styles for each core block when a bundled version provided.
    	if ( $is_core_block && ! wp_should_load_separate_core_block_assets() ) {
    		return false;
    	}

    	$style_path      = remove_block_asset_path_prefix( $style_handle );
    	$is_style_handle = $style_handle === $style_path;
    	// Allow only passing style handles for core blocks.
    	if ( $is_core_block && ! $is_style_handle ) {
    		return false;
    	}
    	// Return the style handle unless it's the first item for every core block that requires special treatment.
    	if ( $is_style_handle && ! ( $is_core_block && 0 === $index ) ) {
    		return $style_handle;
    	}

    	// Check whether styles should have a ".min" suffix or not.
    	$suffix = SCRIPT_DEBUG ? '' : '.min';
    	if ( $is_core_block ) {
    		$style_path = ( 'editorStyle' === $field_name ) ? "editor{$suffix}.css" : "style{$suffix}.css";
    	}

    	$style_path_norm = wp_normalize_path( realpath( dirname( $metadata['file'] ) . '/' . $style_path ) );
    	$style_uri       = get_block_asset_url( $style_path_norm );

    	$block_version = ! $is_core_block && isset( $metadata['version'] ) ? $metadata['version'] : false;
    	$version       = $style_path_norm && defined( 'SCRIPT_DEBUG' ) && SCRIPT_DEBUG ? filemtime( $style_path_norm ) : $block_version;
    	$result        = wp_register_style(
    		$style_handle_name,
    		$style_uri,
    		array(),
    		$version
    	);
    	if ( ! $result ) {
    		return false;
    	}

    	if ( $style_uri ) {
    		wp_style_add_data( $style_handle_name, 'path', $style_path_norm );

    		if ( $is_core_block ) {
    			$rtl_file = str_replace( "{$suffix}.css", "-rtl{$suffix}.css", $style_path_norm );
    		} else {
    			$rtl_file = str_replace( '.css', '-rtl.css', $style_path_norm );
    		}

    		if ( is_rtl() && file_exists( $rtl_file ) ) {
    			wp_style_add_data( $style_handle_name, 'rtl', 'replace' );
    			wp_style_add_data( $style_handle_name, 'suffix', $suffix );
    			wp_style_add_data( $style_handle_name, 'path', $rtl_file );
    		}
    	}

    	return $style_handle_name;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/blocks.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.0/src/wp-includes/blocks.php#L300)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.0/src/wp-includes/blocks.php#L300-L379)

## 󠀁[Related](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#related)󠁿

| Uses | Description | 
| [get_block_asset_url()](https://developer.wordpress.org/reference/functions/get_block_asset_url/)`wp-includes/blocks.php` |

Gets the URL to a block asset.

  | 
| [wp_should_load_separate_core_block_assets()](https://developer.wordpress.org/reference/functions/wp_should_load_separate_core_block_assets/)`wp-includes/script-loader.php` |

Checks whether separate styles should be loaded for core blocks.

  | 
| [generate_block_asset_handle()](https://developer.wordpress.org/reference/functions/generate_block_asset_handle/)`wp-includes/blocks.php` |

Generates the name for an asset based on the name of the block and the field name provided.

  | 
| [remove_block_asset_path_prefix()](https://developer.wordpress.org/reference/functions/remove_block_asset_path_prefix/)`wp-includes/blocks.php` |

Removes the block asset’s path prefix if provided.

  | 
| [wp_normalize_path()](https://developer.wordpress.org/reference/functions/wp_normalize_path/)`wp-includes/functions.php` |

Normalizes a filesystem path.

  | 
| [is_rtl()](https://developer.wordpress.org/reference/functions/is_rtl/)`wp-includes/l10n.php` |

Determines whether the current locale is right-to-left (RTL).

  | 
| [wp_style_is()](https://developer.wordpress.org/reference/functions/wp_style_is/)`wp-includes/functions.wp-styles.php` |

Checks whether a CSS stylesheet has been added to the queue.

  | 
| [wp_register_style()](https://developer.wordpress.org/reference/functions/wp_register_style/)`wp-includes/functions.wp-styles.php` |

Registers a CSS stylesheet.

  | 
| [wp_style_add_data()](https://developer.wordpress.org/reference/functions/wp_style_add_data/)`wp-includes/functions.wp-styles.php` |

Adds metadata to a CSS stylesheet.

  |

[Show 4 more](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#)
[Show less](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#)

| Used by | Description | 
| [register_block_type_from_metadata()](https://developer.wordpress.org/reference/functions/register_block_type_from_metadata/)`wp-includes/blocks.php` |

Registers a block type from the metadata stored in the `block.json` file.

  |

## 󠀁[Changelog](https://developer.wordpress.org/reference/functions/register_block_style_handle/?output_format=md#changelog)󠁿

| Version | Description | 
| [6.1.0](https://developer.wordpress.org/reference/since/6.1.0/) | Added `$index` parameter. | 
| [5.5.0](https://developer.wordpress.org/reference/since/5.5.0/) | Introduced. |

## User Contributed Notes

You must [log in](https://login.wordpress.org/?redirect_to=https%3A%2F%2Fdeveloper.wordpress.org%2Freference%2Ffunctions%2Fregister_block_style_handle%2F)
before being able to contribute a note or feedback.