WordPress · t-hamano · Oct 1, 2025 · Aug 8, 2025 · Aug 15, 2025 · Aug 15, 2025
diff --git a/docs/reference-guides/block-api/block-supports.md b/docs/reference-guides/block-api/block-supports.md
@@ -174,6 +174,32 @@ attributes: {
 }
 ```
 
+## blockVisibility
+
+_**Note:** Since WordPress 6.9._
+
+-   Type: `boolean`
+-   Default value: `true`
+
+By default, a block can be hidden within the editor from the block "Options" dropdown or the block toolbar. To disable this behavior for a block, set `blockVisibility` to `false`.
+
+```js
+supports: {
+	// Don't allow the block to be hidden via the editor UI.
+	blockVisibility: false
+}
+```
+
+When a block is hidden, the state is stored in the block's `metadata` attribute:
+
+```js
+attributes: {
+	metadata: {
+		blockVisibility: false
+	}
+}
+```
+
 ## className
 
 -   Type: `boolean`

@@ -86,7 +86,7 @@ Reuse this design across your site. ([Source](https://github.com/WordPress/guten
 
 -	**Name:** core/block
 -	**Category:** reusable
--	**Supports:** interactivity (clientNavigation), ~~customClassName~~, ~~html~~, ~~inserter~~, ~~renaming~~
+-	**Supports:** interactivity (clientNavigation), ~~blockVisibility~~, ~~customClassName~~, ~~html~~, ~~inserter~~, ~~renaming~~
 -	**Attributes:** content, ref
 
 ## Button
@@ -585,7 +585,7 @@ Show a block pattern. ([Source](https://github.com/WordPress/gutenberg/tree/trun
 
 -	**Name:** core/pattern
 -	**Category:** theme
--	**Supports:** interactivity (clientNavigation), ~~html~~, ~~inserter~~, ~~renaming~~
+-	**Supports:** interactivity (clientNavigation), ~~blockVisibility~~, ~~html~~, ~~inserter~~, ~~renaming~~
 -	**Attributes:** slug
 
 ## Author
@@ -975,7 +975,7 @@ Edit the different global regions of your site, like the header, footer, sidebar
 
 -	**Name:** core/template-part
 -	**Category:** theme
--	**Supports:** align, interactivity (clientNavigation), ~~html~~, ~~renaming~~, ~~reusable~~
+-	**Supports:** align, interactivity (clientNavigation), ~~blockVisibility~~, ~~html~~, ~~renaming~~, ~~reusable~~
 -	**Attributes:** area, slug, tagName, theme
 
 ## Term Description

@@ -0,0 +1,27 @@
+<?php
+/**
+ * Block visibility block support flag.
+ *
+ * @package gutenberg
+ */
+
+/**
+ * Render nothing if the block is hidden.
+ *
+ * @param string $block_content The block content.
+ * @param array  $block         The block.
+ *
+ * @return string The block content.
+ */
+function gutenberg_render_block_visibility_support( $block_content, $block ) {
+	if ( isset( $block['attrs']['metadata']['blockVisibility'] ) && false === $block['attrs']['metadata']['blockVisibility'] ) {
+		return '';
+	}
+
+	return $block_content;
+}
+
+if ( function_exists( 'wp_render_block_visibility_support' ) ) {
+	remove_filter( 'render_block', 'wp_render_block_visibility_support' );
+}
+add_filter( 'render_block', 'gutenberg_render_block_visibility_support', 10, 2 );
@@ -152,6 +152,7 @@ function gutenberg_is_experiment_enabled( $name ) {
 require __DIR__ . '/block-supports/background.php';
 require __DIR__ . '/block-supports/block-style-variations.php';
 require __DIR__ . '/block-supports/aria-label.php';
+require __DIR__ . '/block-supports/block-visibility.php';
 
 // Data views.
 require_once __DIR__ . '/experimental/data-views.php';

@@ -632,6 +632,9 @@ function BlockListBlockProvider( props ) {
 				return previewContext;
 			}
 
+			const { isBlockHidden: _isBlockHidden } = unlock(
+				select( blockEditorStore )
+			);
 			const _isSelected = isBlockSelected( clientId );
 			const canRemove = canRemoveBlock( clientId );
 			const canMove = canMoveBlock( clientId );
@@ -705,6 +708,7 @@ function BlockListBlockProvider( props ) {
 				originalBlockClientId: isInvalid
 					? blocksWithSameName[ 0 ]
 					: false,
+				isBlockHidden: _isBlockHidden( clientId ),
 			};
 		},
 		[ clientId, rootClientId ]
@@ -747,6 +751,7 @@ function BlockListBlockProvider( props ) {
 		className,
 		defaultClassName,
 		originalBlockClientId,
+		isBlockHidden,
 	} = selectedProps;
 
 	// Users of the editor.BlockListBlock filter used to be able to
@@ -797,6 +802,15 @@ function BlockListBlockProvider( props ) {
 		canMove,
 	};
 
+	if (
+		isBlockHidden &&
+		! isSelected &&
+		! isMultiSelected &&
+		! hasChildSelected
+	) {
+		return null;
+	}
+
 	// Here we separate between the props passed to BlockListBlock and any other
 	// information we selected for internal use. BlockListBlock is a filtered
 	// component and thus ALL the props are PUBLIC API.

@@ -6,6 +6,7 @@ import {
 	MenuGroup,
 	__experimentalStyleProvider as StyleProvider,
 } from '@wordpress/components';
+import { hasBlockSupport } from '@wordpress/blocks';
 import { useSelect } from '@wordpress/data';
 
 /**
@@ -20,13 +21,20 @@ import { store as blockEditorStore } from '../../store';
 import BlockModeToggle from '../block-settings-menu/block-mode-toggle';
 import { ModifyContentLockMenuItem } from '../content-lock';
 import { BlockRenameControl, useBlockRename } from '../block-rename';
+import { BlockVisibilityMenuItem } from '../block-visibility';
 
 const { Fill, Slot } = createSlotFill( 'BlockSettingsMenuControls' );
 
 const BlockSettingsMenuControlsSlot = ( { fillProps, clientIds = null } ) => {
-	const { selectedBlocks, selectedClientIds, isContentOnly } = useSelect(
+	const {
+		selectedBlocks,
+		selectedClientIds,
+		isContentOnly,
+		canToggleSelectedBlocksVisibility,
+	} = useSelect(
 		( select ) => {
 			const {
+				getBlocksByClientId,
 				getBlockNamesByClientId,
 				getSelectedBlockClientIds,
 				getBlockEditingMode,
@@ -38,6 +46,11 @@ const BlockSettingsMenuControlsSlot = ( { fillProps, clientIds = null } ) => {
 				selectedClientIds: ids,
 				isContentOnly:
 					getBlockEditingMode( ids[ 0 ] ) === 'contentOnly',
+				canToggleSelectedBlocksVisibility: getBlocksByClientId(
+					ids
+				).every( ( block ) =>
+					hasBlockSupport( block.name, 'blockVisibility', true )
+				),
 			};
 		},
 		[ clientIds ]
@@ -49,6 +62,8 @@ const BlockSettingsMenuControlsSlot = ( { fillProps, clientIds = null } ) => {
 		selectedClientIds.length === 1 && canLock && ! isContentOnly;
 	const showRenameButton =
 		selectedClientIds.length === 1 && canRename && ! isContentOnly;
+	const showVisibilityButton =
+		canToggleSelectedBlocksVisibility && ! isContentOnly;
 
 	// Check if current selection of blocks is Groupable or Ungroupable
 	// and pass this props down to ConvertToGroupButton.
@@ -93,6 +108,11 @@ const BlockSettingsMenuControlsSlot = ( { fillProps, clientIds = null } ) => {
 								clientId={ selectedClientIds[ 0 ] }
 							/>
 						) }
+						{ showVisibilityButton && (
+							<BlockVisibilityMenuItem
+								clientIds={ selectedClientIds }
+							/>
+						) }
 						{ fills }
 						{ selectedClientIds.length === 1 && (
 							<ModifyContentLockMenuItem

@@ -28,6 +28,7 @@ import BlockControls from '../block-controls';
 import __unstableBlockToolbarLastItem from './block-toolbar-last-item';
 import BlockSettingsMenu from '../block-settings-menu';
 import { BlockLockToolbar } from '../block-lock';
+import { BlockVisibilityToolbar } from '../block-visibility';
 import { BlockGroupToolbar } from '../convert-to-group-buttons';
 import BlockEditVisuallyButton from '../block-edit-visually-button';
 import { useShowHoveredOrFocusedGestures } from './utils';
@@ -73,6 +74,7 @@ export function PrivateBlockToolbar( {
 		showSlots,
 		showGroupButtons,
 		showLockButtons,
+		showBlockVisibilityButton,
 		showSwitchSectionStyleButton,
 		hasFixedToolbar,
 		isNavigationMode,
@@ -153,6 +155,7 @@ export function PrivateBlockToolbar( {
 			showSlots: ! _isZoomOut,
 			showGroupButtons: ! _isZoomOut,
 			showLockButtons: ! _isZoomOut,
+			showBlockVisibilityButton: ! _isZoomOut,
 			showSwitchSectionStyleButton:
 				_isZoomOut ||
 				( isNavigationModeEnabled &&
@@ -221,6 +224,13 @@ export function PrivateBlockToolbar( {
 						>
 							<ToolbarGroup className="block-editor-block-toolbar__block-controls">
 								<BlockSwitcher clientIds={ blockClientIds } />
+								{ ! isMultiToolbar &&
+									isDefaultEditingMode &&
+									showBlockVisibilityButton && (
+										<BlockVisibilityToolbar
+											clientId={ blockClientId }
+										/>
+									) }
 								{ ! isMultiToolbar &&
 									isDefaultEditingMode &&
 									showLockButtons && (

@@ -0,0 +1,2 @@
+export { default as BlockVisibilityMenuItem } from './menu-item';
+export { default as BlockVisibilityToolbar } from './toolbar';
@@ -0,0 +1,47 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { MenuItem } from '@wordpress/components';
+import { seen, unseen } from '@wordpress/icons';
+import { useSelect, useDispatch } from '@wordpress/data';
+
+/**
+ * Internal dependencies
+ */
+import { cleanEmptyObject } from '../../hooks/utils';
+import { store as blockEditorStore } from '../../store';
+
+export default function BlockVisibilityMenuItem( { clientIds } ) {
+	const { updateBlockAttributes } = useDispatch( blockEditorStore );
+	const blocks = useSelect(
+		( select ) => {
+			return select( blockEditorStore ).getBlocksByClientId( clientIds );
+		},
+		[ clientIds ]
+	);
+
+	const hasHiddenBlock = blocks.some(
+		( block ) => block.attributes.metadata?.blockVisibility === false
+	);
+
+	const toggleBlockVisibility = () => {
+		blocks.forEach( ( block ) => {
+			updateBlockAttributes( block.clientId, {
+				metadata: cleanEmptyObject( {
+					...block.attributes?.metadata,
+					blockVisibility: hasHiddenBlock ? undefined : false,
+				} ),
+			} );
+		} );
+	};
+
+	return (
+		<MenuItem
+			icon={ hasHiddenBlock ? seen : unseen }
+			onClick={ toggleBlockVisibility }
+		>
+			{ hasHiddenBlock ? __( 'Show' ) : __( 'Hide' ) }
+		</MenuItem>
+	);
+}
@@ -0,0 +1,76 @@
+/**
+ * WordPress dependencies
+ */
+import { __ } from '@wordpress/i18n';
+import { ToolbarButton, ToolbarGroup } from '@wordpress/components';
+import { useRef, useEffect } from '@wordpress/element';
+import { seen, unseen } from '@wordpress/icons';
+import { useSelect, useDispatch } from '@wordpress/data';
+import { hasBlockSupport } from '@wordpress/blocks';
+
+/**
+ * Internal dependencies
+ */
+import { store as blockEditorStore } from '../../store';
+import { unlock } from '../../lock-unlock';
+
+export default function BlockVisibilityToolbar( { clientId } ) {
+	const { canToggleBlockVisibility, isBlockHidden } = useSelect(
+		( select ) => {
+			const { getBlockName } = select( blockEditorStore );
+			const { isBlockHidden: _isBlockHidden } = unlock(
+				select( blockEditorStore )
+			);
+			return {
+				canToggleBlockVisibility: hasBlockSupport(
+					getBlockName( clientId ),
+					'blockVisibility',
+					true
+				),
+				isBlockHidden: _isBlockHidden( clientId ),
+			};
+		},
+		[ clientId ]
+	);
+	const hasBlockVisibilityButtonShownRef = useRef( false );
+	const { updateBlockAttributes } = useDispatch( blockEditorStore );
+
+	// If the block visibility button has been shown, we don't want to
+	// remove it from the toolbar until the toolbar is rendered again
+	// without it. Removing it beforehand can cause focus loss issues.
+	// It needs to return focus from whence it came, and to do that,
+	// we need to leave the button in the toolbar.
+	useEffect( () => {
+		if ( isBlockHidden ) {
+			hasBlockVisibilityButtonShownRef.current = true;
+		}
+	}, [ isBlockHidden ] );
+
+	if ( ! isBlockHidden && ! hasBlockVisibilityButtonShownRef.current ) {
+		return null;
+	}
+
+	const label = isBlockHidden ? __( 'Show' ) : __( 'Hide' );
+
+	return (
+		<>
+			<ToolbarGroup className="block-editor-block-lock-toolbar">
+				<ToolbarButton
+					disabled={ ! canToggleBlockVisibility }
+					icon={ isBlockHidden ? unseen : seen }
+					label={ label }
+					onClick={ () => {
+						const newBlockHidden = ! isBlockHidden;
+						updateBlockAttributes( [ clientId ], {
+							metadata: {
+								blockVisibility: newBlockHidden
+									? false
+									: undefined,
+							},
+						} );
+					} }
+				/>
+			</ToolbarGroup>
+		</>
+	);
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		export { default as BlockVisibilityMenuItem } from './menu-item';
		export { default as BlockVisibilityToolbar } from './toolbar';