Icons: Support keyword-based search in the icons registry

backport-changelog/7.2/13672.md

@@ -0,0 +1,3 @@
+https://github.com/WordPress/wordpress-develop/pull/13672
+
+* https://github.com/WordPress/gutenberg/pull/82367

lib/class-wp-icons-registry-gutenberg.php

@@ -107,11 +107,13 @@ protected function __construct() {}
 	 * @param array  $icon_properties {
 	 *     List of properties for the icon.
 	 *
-	 *     @type string $label     Required. A human-readable label for the icon.
-	 *     @type string $content   Optional. SVG markup for the icon.
-	 *                             If not provided, the content will be retrieved from the `file_path` if set.
-	 *                             If both `content` and `file_path` are not set, the icon will not be registered.
-	 *     @type string $file_path Optional. The full path to the file containing the icon content.
+	 *     @type string   $label     Required. A human-readable label for the icon.
+	 *     @type string   $content   Optional. SVG markup for the icon.
+	 *                               If not provided, the content will be retrieved from the `file_path` if set.
+	 *                               If both `content` and `file_path` are not set, the icon will not be registered.
+	 *     @type string   $file_path Optional. The full path to the file containing the icon content.
+	 *     @type string[] $keywords  Optional. Additional search terms for the icon, matched by
+	 *                               `get_registered_icons()` alongside the name and label.
 	 * }
 	 * @return bool True if the icon was registered with success and false otherwise.
 	 */
@@ -154,7 +156,7 @@ public function register( $icon_name, $icon_properties ) {
 			return false;
 		}
 
-		$allowed_keys = array_fill_keys( array( 'label', 'content', 'file_path' ), 1 );
+		$allowed_keys = array_fill_keys( array( 'label', 'content', 'file_path', 'keywords' ), 1 );
 		foreach ( array_keys( $icon_properties ) as $key ) {
 			if ( ! array_key_exists( $key, $allowed_keys ) ) {
 				_doing_it_wrong(
@@ -192,6 +194,28 @@ public function register( $icon_name, $icon_properties ) {
 			return false;
 		}
 
+		if ( array_key_exists( 'keywords', $icon_properties ) ) {
+			if ( ! is_array( $icon_properties['keywords'] ) ) {
+				_doing_it_wrong(
+					__METHOD__,
+					__( 'Icon keywords must be an array of strings.', 'gutenberg' ),
+					'7.2.0'
+				);
+				return false;
+			}
+
+			foreach ( $icon_properties['keywords'] as $keyword ) {
+				if ( ! is_string( $keyword ) ) {
+					_doing_it_wrong(
+						__METHOD__,
+						__( 'Icon keywords must be an array of strings.', 'gutenberg' ),
+						'7.2.0'
+					);
+					return false;
+				}
+			}
+		}
+
 		if (
 			( ! isset( $icon_properties['content'] ) && ! isset( $icon_properties['file_path'] ) ) ||
 			( isset( $icon_properties['content'] ) && isset( $icon_properties['file_path'] ) )
@@ -338,16 +362,45 @@ protected function get_content( $icon_name ) {
 	}
 
 	/**
-	 * Modified to also search in icon labels
+	 * Determines whether an icon matches a search term.
+	 *
+	 * The term is matched case-insensitively against the icon's name, its label,
+	 * and any of its keywords.
+	 *
+	 * @param array  $icon   Registered icon properties.
+	 * @param string $search Search term.
+	 * @return bool True if the icon matches the search term, false otherwise.
+	 */
+	protected function icon_matches_search( $icon, $search ) {
+		if ( false !== stripos( $icon['name'], $search ) ) {
+			return true;
+		}
+
+		if ( false !== stripos( $icon['label'], $search ) ) {
+			return true;
+		}
+
+		foreach ( $icon['keywords'] ?? array() as $keyword ) {
+			if ( false !== stripos( $keyword, $search ) ) {
+				return true;
+			}
+		}
+
+		return false;
+	}
+
+	/**
+	 * Modified to also search in icon labels and keywords.
+	 *
+	 * @param string $search Optional. Search term matched against each icon's name,
+	 *                       label, and keywords. Default empty string, which returns
+	 *                       every registered icon.
 	 */
 	public function get_registered_icons( $search = '' ) {
 		$icons = array();
 
 		foreach ( $this->registered_icons as $icon ) {
-			if ( ! empty( $search )
-				&& false === stripos( $icon['name'], $search )
-				&& false === stripos( $icon['label'], $search )
-			) {
+			if ( ! empty( $search ) && ! $this->icon_matches_search( $icon, $search ) ) {
 				continue;
 			}
 
@@ -384,6 +437,9 @@ public static function get_instance() {
 					} else {
 						continue;
 					}
+					if ( ! empty( $icon['keywords'] ) ) {
+						$icon_properties['keywords'] = $icon['keywords'];
+					}
 					$gutenberg_registry->register( $icon['name'], $icon_properties );
 				}
 			}

lib/class-wp-rest-icons-controller-gutenberg.php

@@ -166,8 +166,8 @@ public function get_icon( $name ) {
 	/**
 	 * Prepare a raw icon before it gets output in a REST API response.
 	 *
-	 * Adds a `collection` field to the base response while keeping the
-	 * namespaced icon name (e.g. `core/arrow-left`) as the `name` field.
+	 * Adds `collection` and `keywords` fields to the base response while keeping
+	 * the namespaced icon name (e.g. `core/arrow-left`) as the `name` field.
 	 *
 	 * @param array           $item    Raw icon as registered.
 	 * @param WP_REST_Request $request Request object.
@@ -183,6 +183,12 @@ public function prepare_item_for_response( $item, $request ) {
 			$response->set_data( $data );
 		}
 
+		if ( rest_is_field_included( 'keywords', $fields ) ) {
+			$data             = $response->get_data();
+			$data['keywords'] = isset( $item['keywords'] ) ? array_values( $item['keywords'] ) : array();
+			$response->set_data( $data );
+		}
+
 		return $response;
 	}
 
@@ -205,6 +211,14 @@ public function get_item_schema() {
 			'context'     => array( 'view', 'edit', 'embed' ),
 		);
 
+		$schema['properties']['keywords'] = array(
+			'description' => __( 'Additional search terms for the icon.', 'gutenberg' ),
+			'type'        => 'array',
+			'items'       => array( 'type' => 'string' ),
+			'readonly'    => true,
+			'context'     => array( 'view', 'edit', 'embed' ),
+		);
+
 		$this->schema = $schema;
 
 		return $this->add_additional_fields_schema( $this->schema );

lib/compat/wordpress-7.1/icons.php

@@ -51,11 +51,13 @@ function wp_unregister_icon_collection( $slug ) {
 	 * @param array  $args      {
 	 *     List of properties for the icon.
 	 *
-	 *     @type string $label     Required. A human-readable label for the icon.
-	 *     @type string $content   Optional. SVG markup for the icon.
-	 *                             If not provided, the content will be retrieved from the `file_path` if set.
-	 *                             If both `content` and `file_path` are not set, the icon will not be registered.
-	 *     @type string $file_path Optional. The full path to the file containing the icon content.
+	 *     @type string   $label     Required. A human-readable label for the icon.
+	 *     @type string   $content   Optional. SVG markup for the icon.
+	 *                               If not provided, the content will be retrieved from the `file_path` if set.
+	 *                               If both `content` and `file_path` are not set, the icon will not be registered.
+	 *     @type string   $file_path Optional. The full path to the file containing the icon content.
+	 *     @type string[] $keywords  Optional. Additional search terms for the icon, matched by
+	 *                               `get_registered_icons()` alongside the name and label.
 	 * }
 	 * @return bool True if the icon was registered successfully, else false.
 	 */

lib/icons.php

@@ -86,6 +86,10 @@ function gutenberg_register_default_icons() {
 			'file_path' => $icons_directory . $icon_data['filePath'],
 		);
 
+		if ( isset( $icon_data['keywords'] ) ) {
+			$icon_args['keywords'] = $icon_data['keywords'];
+		}
+
 		foreach ( $icon_data['collections'] as $collection_slug ) {
 			wp_register_icon( $collection_slug . '/' . $icon_name, $icon_args );
 		}

packages/block-library/CHANGELOG.md

@@ -8,6 +8,7 @@
 -   Columns: Remove the column count slider from the block settings ([#83262](https://github.com/WordPress/gutenberg/pull/83262)).
 -   Media & Text: Lower the specificity of the content area's default padding so themes can override it, including through the block's custom CSS in `theme.json` ([#83563](https://github.com/WordPress/gutenberg/pull/83563)).
 -   Gallery: Add an "Order by" sorting control to the static gallery mode, and consolidate sorting control for static and dynamic modes in the Settings panel ([#83438](https://github.com/WordPress/gutenberg/pull/83438)).
+-   Icon: Match an icon's keywords as well as its name and label when searching the icon library ([#82367](https://github.com/WordPress/gutenberg/pull/82367)).
 
 ### Bug Fixes
 

packages/block-library/src/icon/components/custom-inserter/index.jsx

@@ -65,7 +65,11 @@ export default function CustomInserterModal( { onClose, value, onChange } ) {
 				const iconLabel = normalizeSearchInput( icon.label );
 
 				return (
-					iconName.includes( input ) || iconLabel.includes( input )
+					iconName.includes( input ) ||
+					iconLabel.includes( input ) ||
+					( icon.keywords ?? [] ).some( ( keyword ) =>
+						normalizeSearchInput( keyword ).includes( input )
+					)
 				);
 			} );
 		}

packages/core-data/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   `Icon`: add the `keywords` field exposed by the icons REST endpoint ([#82367](https://github.com/WordPress/gutenberg/pull/82367)).
+
 ### Internal
 
 -   Added an internal entity sync interface: `registerEntitySyncManager` and `getEntitySyncManager` let one manager plug into the entity lifecycle (record loads, edits, saves, deletes, and undo). The real-time collaboration experiment now runs through it instead of being called directly by the store. The interface is not exposed outside the package yet ([#83410](https://github.com/WordPress/gutenberg/pull/83410)).

packages/core-data/src/entity-types/icon.ts

@@ -21,6 +21,10 @@ declare module './base-entity-records' {
 			 * The slug of the collection this icon belongs to.
 			 */
 			collection?: string;
+			/**
+			 * Additional search terms for the icon.
+			 */
+			keywords?: string[];
 		}
 	}
 }

packages/icons/CHANGELOG.md

@@ -11,6 +11,7 @@
 -   `formatBold`: draw the B with heavier vertical strokes so it reads as bold at a glance ([#83321](https://github.com/WordPress/gutenberg/pull/83321)).
 -   `justifySpaceBetween` and `justifySpaceEvenly`: redraw so the two icons share one construction with the new `justifySpaceAround`, differing only in where the blocks sit ([#83519](https://github.com/WordPress/gutenberg/pull/83519)).
 -   `headingLevel1` to `headingLevel6`: enlarge the drawings to improve their optical balance with the rest of the set ([#83268](https://github.com/WordPress/gutenberg/pull/83268)).
+-   `manifest.json`: Add optional `keywords` property to improve discoverability. ([#82367](https://github.com/WordPress/gutenberg/pull/82367))
 
 ### Bug Fixes
 
@@ -124,7 +125,7 @@
 
 ### Breaking Changes
 
-- Rename Tabs-related icons: `tabs-menu` to `tab-list`, `tabs-menu-item` to `tab`, and `tab` to `tab-panel`. ([#77418](https://github.com/WordPress/gutenberg/pull/77418))
+-   Rename Tabs-related icons: `tabs-menu` to `tab-list`, `tabs-menu-item` to `tab`, and `tab` to `tab-panel`. ([#77418](https://github.com/WordPress/gutenberg/pull/77418))
 
 ## 12.2.0 (2026-04-15)
 

packages/icons/README.md

@@ -53,7 +53,7 @@ To add a new icon to the library, follow these steps:
    - `collections` (optional): The collections the icon is registered in once it ships to WordPress Core. Omit it to keep the icon in the JS library only. **Important**: Once an icon ships to WordPress Core, removing it is difficult, so carefully consider this field before setting it. The available collections are:
      - `core`: the public collection. Its icons are exposed through the SVG Icons API, which makes them selectable in the Icon block.
      - `core-admin`: the collection the WordPress admin interface renders from. It is not public, so its icons are never exposed through the REST API or selectable in the Icon block, and unregistering `core` cannot take them away from the admin interface.
-
+   - `keywords` (optional): An array of additional translatable search terms for the icon (e.g. `[ "hamburger", "navigation" ]` for a Menu icon).
 4. **Do not edit `manifest.php`**: The `manifest.php` file is automatically generated from `manifest.json` by the build script. Do not edit it manually, as your changes will be overwritten when the build runs.
 
 After adding your icon, run `npm run build` to generate the TypeScript files and update `manifest.php`.

packages/icons/lib/generate-manifest-php.cjs

@@ -46,10 +46,23 @@ function generatePHPArray( manifest ) {
 			.map( ( collection ) => `'${ escapePHPString( collection ) }'` )
 			.join( ', ' );
 
+		// Keywords are optional, and are localized like labels since they are
+		// matched against user-entered search terms.
+		const keywords = item.keywords?.length
+			? `\n\t\t'keywords'    => array( ${ item.keywords
+					.map(
+						( keyword ) =>
+							`_x( '${ escapePHPString(
+								keyword
+							) }', 'icon keyword', 'gutenberg' )`
+					)
+					.join( ', ' ) } ),`
+			: '';
+
 		return `${ key } => array(
 		'label'       => _x( '${ label }', 'icon label', 'gutenberg' ),
 		'filePath'    => '${ filePath }',
-		'collections' => array( ${ collections } ),
+		'collections' => array( ${ collections } ),${ keywords }
 	),`;
 	} );
 

packages/icons/lib/validate-collection.cjs

@@ -18,6 +18,7 @@ function isStrokeBasedSvg( svgContent ) {
  * - Each manifest entry has a matching SVG in library/, and vice versa.
  * - Each manifest entry's `collections` property, if present, is a non-empty array of
  *   known collection slugs.
+ * - Each manifest entry's `keywords` property, if present, is an array of strings.
  * - Each SVG uses currentColor so icons inherit text color.
  * - Each SVG uses viewBox="0 0 24 24".
  * - Each stroke-based SVG contains at least one stroked graphical element.
@@ -90,6 +91,25 @@ async function validateCollection() {
 			}
 		}
 
+		/*
+		 * Verify that `keywords`, if present, is an array of strings.
+		 */
+		if (
+			'keywords' in icon &&
+			( ! Array.isArray( icon.keywords ) ||
+				icon.keywords.some(
+					( keyword ) => typeof keyword !== 'string'
+				) )
+		) {
+			problems.push(
+				`- Invalid icon definition for icon '${
+					icon.slug
+				}': expected 'keywords' to be an array of strings, saw ${ JSON.stringify(
+					icon.keywords
+				) }`
+			);
+		}
+
 		/*
 		 * Verify that the corresponding SVG file is found.
 		 */

phpunit/class-wp-icon-collections-registry-test.php

@@ -11,31 +11,48 @@ class WP_Test_Icon_Collections_Registry extends WP_UnitTestCase {
 	 */
 	protected $collections;
 
+	/**
+	 * Icons registry instance in place before the test, restored in tear_down.
+	 *
+	 * @var WP_Icons_Registry|null
+	 */
+	private $original_icons_registry = null;
+
 	public function set_up() {
 		parent::set_up();
 		$this->collections = WP_Icon_Collections_Registry::get_instance();
-	}
-
-	public function tear_down() {
-		foreach ( array( 'plugin-a', 'plugin-b', 'my-collection' ) as $slug ) {
-			if ( $this->collections->is_registered( $slug ) ) {
-				$this->collections->unregister( $slug );
-			}
-		}
-
-		$instance_property = new ReflectionProperty( WP_Icons_Registry_Gutenberg::class, 'instance' );
 
 		/*
+		 * Start from a clean registry, keeping the instance that was in place so
+		 * `tear_down()` can put it back rather than leaving later suites with a
+		 * base registry that rejects Gutenberg-only icon properties.
+		 *
 		 * ReflectionProperty::setAccessible is:
 		 * - redundant as of 8.1.0, which made all properties accessible
 		 * - deprecated as of 8.5.0
 		 * - needed until 8.1.0, as property `instance` is private
 		 */
+		$instance_property = new ReflectionProperty( WP_Icons_Registry_Gutenberg::class, 'instance' );
 		if ( PHP_VERSION_ID < 80100 ) {
 			$instance_property->setAccessible( true );
 		}
-
+		$this->original_icons_registry = $instance_property->getValue();
 		$instance_property->setValue( null, null );
+	}
+
+	public function tear_down() {
+		$instance_property = new ReflectionProperty( WP_Icons_Registry_Gutenberg::class, 'instance' );
+		if ( PHP_VERSION_ID < 80100 ) {
+			$instance_property->setAccessible( true );
+		}
+		$instance_property->setValue( null, $this->original_icons_registry );
+		$this->original_icons_registry = null;
+
+		foreach ( array( 'plugin-a', 'plugin-b', 'my-collection' ) as $slug ) {
+			if ( $this->collections->is_registered( $slug ) ) {
+				$this->collections->unregister( $slug );
+			}
+		}
 
 		parent::tear_down();
 	}