Skip to content

Enable default gap processing on Gallery block #79984

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
tellthemachines merged 5 commits into from
Jul 9, 2026
Merged

Enable default gap processing on Gallery block #79984

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
2b0405e
Enable default gap processing on Gallery block
tellthemachines Jul 8, 2026
e461328
ensure gap value in width calculation is always correct
tellthemachines Jul 8, 2026
935ee6b
clarify custom property output
tellthemachines Jul 8, 2026
f259b87
re-add comments and inline function
tellthemachines Jul 8, 2026
d31efb0
fix errors
tellthemachines Jul 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

1 change: 1 addition & 0 deletions packages/block-library/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,7 @@
"@wordpress/dom": "file:../dom",
"@wordpress/element": "file:../element",
"@wordpress/escape-html": "file:../escape-html",
"@wordpress/global-styles-engine": "file:../global-styles-engine",

@tellthemachines tellthemachines Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Unfortunately we need this because since #79104 we're no longer able to hardcode the value of the media query. i guess this is a symptom of Gallery doing stuff (its custom layout) that should really be done by global styles/block supports 🤷

@talldan talldan Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Block Library already depends on Block Editor, which depends on Global Styles Engine, so not a big deal imo.

"@wordpress/hooks": "file:../hooks",
"@wordpress/html-entities": "file:../html-entities",
"@wordpress/i18n": "file:../i18n",
Expand Down
2 changes: 1 addition & 1 deletion packages/block-library/src/gallery/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,7 +47,7 @@ _Defined via the [`supports`](https://developer.wordpress.org/block-editor/refer
- [`spacing`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#spacing):
- `margin`: `true`
- `padding`: `true`
- `blockGap`: `["horizontal","vertical"]`
- `blockGap`: `{"sides":["horizontal","vertical"],"__experimentalDefault":"var( --wp--style--gallery-gap-default, var( --gallery-block--gutter-size, var( --wp--style--block-gap, 0.5em ) ) )"}`
- [`color`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color):
- [`text`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-text): `false`
- [`background`](https://developer.wordpress.org/block-editor/reference-guides/block-api/block-supports/#color-background): `true`
Expand Down
6 changes: 4 additions & 2 deletions packages/block-library/src/gallery/block.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,10 @@
"spacing": {
"margin": true,
"padding": true,
"blockGap": [ "horizontal", "vertical" ],
"__experimentalSkipSerialization": [ "blockGap" ],
"blockGap": {
"sides": [ "horizontal", "vertical" ],
"__experimentalDefault": "var( --wp--style--gallery-gap-default, var( --gallery-block--gutter-size, var( --wp--style--block-gap, 0.5em ) ) )"

@tellthemachines tellthemachines Jul 8, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems that --wp--style--gallery-gap-default is a way of allowing themes to set a default gap on the Gallery block. We should probably deprecate it in favour of declaring the value in theme.json but I'm not sure how valuable it might still be for classic themes. Worth looking into separately perhaps.

--gallery-block--gutter-size is I think similar but deprecated, and only preserved for back compat.

},
"__experimentalDefaultControls": {
"blockGap": true,
"margin": false,
Expand Down
6 changes: 3 additions & 3 deletions packages/block-library/src/gallery/edit.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ import {
import useImageSizes from './use-image-sizes';
import useGetNewImages from './use-get-new-images';
import useGetMedia from './use-get-media';
import GapStyles from './gap-styles';
import GalleryGapCustomProperties from './gap-styles';
import useDynamicGallery from './use-dynamic-gallery';
import { GallerySourcePanel, GalleryDynamicView } from './dynamic-gallery';
import { getDynamicSource, ATTACHED_MEDIA } from './dynamic-source';
Expand Down Expand Up @@ -941,8 +941,8 @@ export default function GalleryEdit( props ) {
/>
</BlockControls>
) }
<GapStyles
blockGap={ attributes.style?.spacing?.blockGap }
<GalleryGapCustomProperties
style={ attributes.style }
clientId={ clientId }
/>
</>
Expand Down
63 changes: 43 additions & 20 deletions packages/block-library/src/gallery/gap-styles.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,34 +4,57 @@
import {
__experimentalGetGapCSSValue as getGapCSSValue,
useStyleOverride,
useSettings,
} from '@wordpress/block-editor';
import { privateApis as globalStylesEnginePrivateApis } from '@wordpress/global-styles-engine';

export default function GapStyles( { blockGap, clientId } ) {
// --gallery-block--gutter-size is deprecated. --wp--style--gallery-gap-default should be used by themes that want to set a default
// gap on the gallery.
const fallbackValue = `var( --wp--style--gallery-gap-default, var( --gallery-block--gutter-size, var( --wp--style--block-gap, 0.5em ) ) )`;
let gapValue = fallbackValue;
let column = fallbackValue;
let row;

// Check for the possibility of split block gap values. See: https://github.com/WordPress/gutenberg/pull/37736
if ( !! blockGap ) {
row =
typeof blockGap === 'string'
? getGapCSSValue( blockGap )
: getGapCSSValue( blockGap?.top ) || fallbackValue;
/**
* Internal dependencies
*/
import { unlock } from '../lock-unlock';

const { getResponsiveMediaQueries } = unlock( globalStylesEnginePrivateApis );

// --gallery-block--gutter-size is deprecated. --wp--style--gallery-gap-default should be used by themes that want to set a default
// gap on the gallery.
const FALLBACK_VALUE = `var( --wp--style--gallery-gap-default, var( --gallery-block--gutter-size, var( --wp--style--block-gap, 0.5em ) ) )`;

function getGalleryGapCustomPropertyStyle( selector, blockGap ) {
let column = FALLBACK_VALUE;
if ( blockGap ) {
column =
typeof blockGap === 'string'
? getGapCSSValue( blockGap )
: getGapCSSValue( blockGap?.left ) || fallbackValue;
gapValue = row === column ? row : `${ row } ${ column }`;
? getGapCSSValue( blockGap ) || FALLBACK_VALUE
: getGapCSSValue( blockGap?.left ) || FALLBACK_VALUE;
}

// The unstable gallery gap calculation requires a real value (such as `0px`) and not `0`.
const gap = `#block-${ clientId } {
--wp--style--unstable-gallery-gap: ${ column === '0' ? '0px' : column };
gap: ${ gapValue }
return `${ selector } {
--wp--style--unstable-gallery-gap: ${ column === '0' ? '0px' : column }
}`;
}

export default function GalleryGapCustomProperties( { style, clientId } ) {
const selector = `#block-${ clientId }`;
const [ viewportSettings ] = useSettings( 'viewport' );
let gap = getGalleryGapCustomPropertyStyle(
selector,
style?.spacing?.blockGap
);

Object.entries( getResponsiveMediaQueries( viewportSettings ) ).forEach(
( [ viewport, mediaQuery ] ) => {
const viewportBlockGap = style?.[ viewport ]?.spacing?.blockGap;
if ( viewportBlockGap === undefined || viewportBlockGap === null ) {
return;
}

gap += `${ mediaQuery }{${ getGalleryGapCustomPropertyStyle(
selector,
viewportBlockGap
) }}`;
}
);

useStyleOverride( { css: gap } );

Expand Down
119 changes: 74 additions & 45 deletions packages/block-library/src/gallery/index.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -52,6 +52,41 @@ function block_core_gallery_render_context( $context, $parsed_block ) {

add_filter( 'render_block_context', 'block_core_gallery_render_context', 10, 2 );

/**
* Returns the column gap value used for Gallery image width calculations.
*
* @since 7.1.0
*
* @param string|array|null $gap Gallery block gap value.
* @param string $fallback_gap Fallback gap value.
* @return string Gallery column gap value.
*/
function block_core_gallery_get_column_gap_value( $gap, $fallback_gap ) {
if ( is_array( $gap ) ) {
$gap = $gap['left'] ?? $fallback_gap;
}

// Make sure $gap is a string to avoid PHP 8.1 deprecation error in preg_match() when the value is null.
$gap = is_string( $gap ) ? $gap : '';
Comment on lines +69 to +70

@talldan talldan Jul 8, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like it was like this in trunk, so not something that needs to be changed, but it's a bit unusual that this code goes to the effort of passing an empty string into preg_match like this. It's ultimately not going to do anything. I guess it was probably quickly patched to avoid the PHP 8.1 error.


// Skip if gap value contains unsupported characters.
// Regex for CSS value borrowed from `safecss_filter_attr`, and used here
// because we only want to match against the value, not the CSS attribute.
$gap = $gap && preg_match( '%[\\\(&=}]|/\*%', $gap ) ? null : $gap;

// Get spacing CSS variable from preset value if provided.
if ( is_string( $gap ) && str_contains( $gap, 'var:preset|spacing|' ) ) {
$index_to_splice = strrpos( $gap, '|' ) + 1;
$slug = _wp_to_kebab_case( substr( $gap, $index_to_splice ) );
$gap = "var(--wp--preset--spacing--$slug)";
}

$gap_column = ( null !== $gap && '' !== $gap ) ? $gap : $fallback_gap;

// The unstable gallery gap calculation requires a real value (such as `0px`) and not `0`.
return '0' === $gap_column ? '0px' : $gap_column;
}

/**
* Resolves a Gallery block's `dynamicContent` to an ordered list of image
* attachment IDs.
Expand Down Expand Up @@ -345,36 +380,15 @@ function block_core_gallery_render( $attributes, $content, $block ) {
// the current gap setting in order to maintain the number of flex columns
// so a css var is added to allow this.

$gap = $attributes['style']['spacing']['blockGap'] ?? null;
// Skip if gap value contains unsupported characters.
// Regex for CSS value borrowed from `safecss_filter_attr`, and used here
// because we only want to match against the value, not the CSS attribute.
if ( is_array( $gap ) ) {
foreach ( $gap as $key => $value ) {
// Make sure $value is a string to avoid PHP 8.1 deprecation error in preg_match() when the value is null.
$value = is_string( $value ) ? $value : '';
$value = $value && preg_match( '%[\\\(&=}]|/\*%', $value ) ? null : $value;

// Get spacing CSS variable from preset value if provided.
if ( is_string( $value ) && str_contains( $value, 'var:preset|spacing|' ) ) {
$index_to_splice = strrpos( $value, '|' ) + 1;
$slug = _wp_to_kebab_case( substr( $value, $index_to_splice ) );
$value = "var(--wp--preset--spacing--$slug)";
}

$gap[ $key ] = $value;
}
} else {
// Make sure $gap is a string to avoid PHP 8.1 deprecation error in preg_match() when the value is null.
$gap = is_string( $gap ) ? $gap : '';
$gap = $gap && preg_match( '%[\\\(&=}]|/\*%', $gap ) ? null : $gap;

// Get spacing CSS variable from preset value if provided.
if ( is_string( $gap ) && str_contains( $gap, 'var:preset|spacing|' ) ) {
$index_to_splice = strrpos( $gap, '|' ) + 1;
$slug = _wp_to_kebab_case( substr( $gap, $index_to_splice ) );
$gap = "var(--wp--preset--spacing--$slug)";
}
$style_attr = is_array( $attributes['style'] ?? null )
? $attributes['style']
: array();
if (
defined( 'IS_GUTENBERG_PLUGIN' ) &&
IS_GUTENBERG_PLUGIN &&
function_exists( 'gutenberg_resolve_style_state_aliases' )
) {
$style_attr = gutenberg_resolve_style_state_aliases( $style_attr, 'core/gallery' );
}

$unique_gallery_classname = wp_unique_id( 'wp-block-gallery-' );
Expand All @@ -385,31 +399,46 @@ function block_core_gallery_render( $attributes, $content, $block ) {
// --gallery-block--gutter-size is deprecated. --wp--style--gallery-gap-default should be used by themes that want to set a default
// gap on the gallery.
$fallback_gap = 'var( --wp--style--gallery-gap-default, var( --gallery-block--gutter-size, var( --wp--style--block-gap, 0.5em ) ) )';
$gap_value = $gap ? $gap : $fallback_gap;
$gap_column = $gap_value;

if ( is_array( $gap_value ) ) {
$gap_row = $gap_value['top'] ?? $fallback_gap;
$gap_column = $gap_value['left'] ?? $fallback_gap;
$gap_value = $gap_row === $gap_column ? $gap_row : $gap_row . ' ' . $gap_column;
}
$gap_column = block_core_gallery_get_column_gap_value( $style_attr['spacing']['blockGap'] ?? null, $fallback_gap );

// The unstable gallery gap calculation requires a real value (such as `0px`) and not `0`.
if ( '0' === $gap_column ) {
$gap_column = '0px';
}

// Set the CSS variable to the column value, and the `gap` property to the combined gap value.
// Set the CSS variable to the column value for Gallery's flex width calculations.
$gallery_styles = array(
array(
'selector' => ".wp-block-gallery.{$unique_gallery_classname}",
'declarations' => array(
'--wp--style--unstable-gallery-gap' => $gap_column,
'gap' => $gap_value,
),
),
);

$global_settings = wp_get_global_settings();
$viewport_settings = $global_settings['viewport'] ?? null;
$responsive_media_queries = array();
foreach ( array( 'WP_Theme_JSON_Gutenberg', 'WP_Theme_JSON' ) as $theme_json_class_name ) {
if ( method_exists( $theme_json_class_name, 'get_viewport_media_queries' ) ) {
$responsive_media_queries = $theme_json_class_name::get_viewport_media_queries( $viewport_settings );
break;
}
}

foreach ( $responsive_media_queries as $breakpoint => $media_query ) {
$viewport_style = $style_attr[ $breakpoint ] ?? null;
if ( ! is_array( $viewport_style ) || ! isset( $viewport_style['spacing']['blockGap'] ) ) {
continue;
}

$gallery_styles[] = array(
'selector' => ".wp-block-gallery.{$unique_gallery_classname}",
'declarations' => array(
'--wp--style--unstable-gallery-gap' => block_core_gallery_get_column_gap_value(
$viewport_style['spacing']['blockGap'],
$fallback_gap
),
),
'rules_group' => $media_query,
);
}

wp_style_engine_get_stylesheet_from_css_rules(
$gallery_styles,
array( 'context' => 'block-supports' )
Expand Down
1 change: 1 addition & 0 deletions packages/block-library/tsconfig.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@
{ "path": "../dom" },
{ "path": "../element" },
{ "path": "../escape-html" },
{ "path": "../global-styles-engine" },
{ "path": "../private-apis" },
{ "path": "../hooks" },
{ "path": "../html-entities" },
Expand Down
Loading