Title: WP_Theme_JSON::update_button_width_declarations
Published: August 20, 2026

---

# WP_Theme_JSON::update_button_width_declarations( array $feature_declarations, array $settings ): array

## In this article

 * [Description](https://developer.wordpress.org/reference/classes/wp_theme_json/update_button_width_declarations/?output_format=md#description)
 * [Parameters](https://developer.wordpress.org/reference/classes/wp_theme_json/update_button_width_declarations/?output_format=md#parameters)
 * [Return](https://developer.wordpress.org/reference/classes/wp_theme_json/update_button_width_declarations/?output_format=md#return)
 * [Source](https://developer.wordpress.org/reference/classes/wp_theme_json/update_button_width_declarations/?output_format=md#source)
 * [Changelog](https://developer.wordpress.org/reference/classes/wp_theme_json/update_button_width_declarations/?output_format=md#changelog)

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

This function’s access is marked private. This means it is not intended for use 
by plugin or theme developers, only by core. It is listed here for completeness.

Updates button width declarations to use a calc() formula for percentage values.

## 󠀁[Description](https://developer.wordpress.org/reference/classes/wp_theme_json/update_button_width_declarations/?output_format=md#description)󠁿

When a percentage width is set on the Button block via Global Styles, the resulting
CSS needs to account for block gap spacing so that buttons tile correctly on a row(
e.g. 4 buttons at 25% width all fit on one row).

This mirrors the dynamic calc() formula applied at the block instance level in the
button block’s stylesheet (style.scss).

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

 `$feature_declarations`arrayrequired

The feature declarations keyed by selector.

`$settings`arrayrequired

The theme.json settings.

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

 array The updated feature declarations.

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

    ```php
    private static function update_button_width_declarations( $feature_declarations, $settings ) {
    	if ( ! isset( $feature_declarations['.wp-block-button'] ) ) {
    		return $feature_declarations;
    	}

    	foreach ( $feature_declarations['.wp-block-button'] as &$declaration ) {
    		if ( 'width' !== $declaration['name'] || ! isset( $declaration['value'] ) ) {
    			continue;
    		}

    		$value      = $declaration['value'];
    		$percentage = null;

    		// Case 1: Direct percentage value e.g. "25%".
    		if ( is_string( $value ) && str_ends_with( $value, '%' ) ) {
    			$percentage = (float) $value;
    		}

    		// Case 2: Preset CSS var e.g. "var(--wp--preset--dimension--50)".
    		if ( null === $percentage && is_string( $value ) && str_starts_with( $value, 'var(--wp--preset--dimension--' ) ) {
    			// Extract the slug from the var name.
    			$slug = substr( $value, strlen( 'var(--wp--preset--dimension--' ), -1 );

    			/*
    			 * Look up the preset size across all origins.
    			 * Check block-level settings first (core/button), then top-level settings.
    			 */
    			$dimension_sizes = ( $settings['blocks']['core/button']['dimensions']['dimensionSizes'] ?? array() )
    				+ ( $settings['dimensions']['dimensionSizes'] ?? array() );
    			foreach ( $dimension_sizes as $origin_sizes ) {
    				if ( ! is_array( $origin_sizes ) ) {
    					continue;
    				}
    				foreach ( $origin_sizes as $preset ) {
    					if ( isset( $preset['slug'] ) && $slug === $preset['slug'] && isset( $preset['size'] ) ) {
    						$size = $preset['size'];
    						if ( is_string( $size ) && str_ends_with( $size, '%' ) ) {
    							$percentage = (float) $size;
    						}
    						break 2;
    					}
    				}
    			}
    		}

    		if ( null === $percentage ) {
    			continue;
    		}

    		/*
    		 * Apply the same calc() formula as the block instance level (style.scss).
    		 * The numeric percentage value is used as a unitless number:
    		 * - Multiplied by 1% to get the percentage width.
    		 * - Divided by 100 to calculate the gap adjustment proportion.
    		 */
    		$declaration['value'] = sprintf(
    			'calc(%s * 1%% - (var(--wp--style--block-gap, 0.5em) * (1 - %s / 100)))',
    			$percentage,
    			$percentage
    		);
    	}
    	unset( $declaration );

    	return $feature_declarations;
    }
    ```

[View all references](https://developer.wordpress.org/reference/files/wp-includes/class-wp-theme-json.php/)
[View on Trac](https://core.trac.wordpress.org/browser/tags/7.1/src/wp-includes/class-wp-theme-json.php#L3434)
[View on GitHub](https://github.com/WordPress/wordpress-develop/blob/7.1/src/wp-includes/class-wp-theme-json.php#L3434-L3498)

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

| Version | Description | 
| [7.1.0](https://developer.wordpress.org/reference/since/7.1.0/) | Introduced. |

## User Contributed Notes

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