Icons: Support keyword-based search in the icons registry

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

@@ -103,15 +103,17 @@ 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 bool   $public    Optional. Whether the icon is exposed through the REST API, and
-	 *                             therefore selectable in the editor's Icon block. Non-public icons
-	 *                             stay available to server-side code via {@see wp_get_icon()}.
-	 *                             Default true.
+	 *     @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 bool     $public    Optional. Whether the icon is exposed through the REST API, and
+	 *                               therefore selectable in the editor's Icon block. Non-public icons
+	 *                               stay available to server-side code via {@see wp_get_icon()}.
+	 *                               Default true.
+	 *     @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', 'public' ), 1 );
+		$allowed_keys = array_fill_keys( array( 'label', 'content', 'file_path', 'public', 'keywords' ), 1 );
 		foreach ( array_keys( $icon_properties ) as $key ) {
 			if ( ! array_key_exists( $key, $allowed_keys ) ) {
 				_doing_it_wrong(
@@ -201,6 +203,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.1.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.1.0'
+					);
+					return false;
+				}
+			}
+		}
+
 		if (
 			( ! isset( $icon_properties['content'] ) && ! isset( $icon_properties['file_path'] ) ) ||
 			( isset( $icon_properties['content'] ) && isset( $icon_properties['file_path'] ) )
@@ -347,16 +371,69 @@ protected function get_content( $icon_name ) {
 	}
 
 	/**
-	 * Modified to also search in icon labels
+	 * Determines whether a string contains a search term, ignoring case.
+	 *
+	 * Labels and keywords are translated, so the comparison is made with
+	 * `mb_stripos()` where mbstring is available, which case-folds multibyte
+	 * characters that `stripos()` only matches byte for byte. `stripos()` is
+	 * the fallback, since mbstring is not guaranteed to be loaded.
+	 *
+	 * @param string $haystack String to search in.
+	 * @param string $needle   Search term.
+	 * @return bool True if the haystack contains the search term, false otherwise.
+	 */
+	private function contains_search_term( $haystack, $needle ) {
+		if ( '' === $needle ) {
+			return true;
+		}
+
+		if ( function_exists( 'mb_stripos' ) ) {
+			return false !== mb_stripos( $haystack, $needle, 0 );
+		}
+
+		return false !== stripos( $haystack, $needle );
+	}
+
+	/**
+	 * 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 ( $this->contains_search_term( $icon['name'], $search ) ) {
+			return true;
+		}
+
+		if ( $this->contains_search_term( $icon['label'], $search ) ) {
+			return true;
+		}
+
+		foreach ( $icon['keywords'] ?? array() as $keyword ) {
+			if ( $this->contains_search_term( $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;
 			}
 
@@ -396,6 +473,9 @@ public static function get_instance() {
 					if ( isset( $icon['public'] ) ) {
 						$icon_properties['public'] = $icon['public'];
 					}
+					if ( ! empty( $icon['keywords'] ) ) {
+						$icon_properties['keywords'] = $icon['keywords'];
+					}
 					$gutenberg_registry->register( $icon['name'], $icon_properties );
 				}
 			}

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

@@ -159,8 +159,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.
@@ -176,6 +176,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;
 	}
 
@@ -198,6 +204,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/icons.php

@@ -73,6 +73,11 @@ function gutenberg_register_default_icons() {
 			$icon_args['public'] = $icon_data['public'];
 		}
 
+		// Keywords are optional, so only pass them through when present.
+		if ( ! empty( $icon_data['keywords'] ) && is_array( $icon_data['keywords'] ) ) {
+			$icon_args['keywords'] = $icon_data['keywords'];
+		}
+
 		wp_register_icon( 'core/' . $icon_name, $icon_args );
 	}
 }

packages/block-library/CHANGELOG.md

@@ -63,6 +63,7 @@
 ### Enhancements
 
 -   Columns: Add transforms between Columns and the Row variation that preserve column widths through flex child sizing controls.
+-   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))
 -   Gallery: Add an opt-in Grid layout while preserving the existing Flex layout for current galleries.([#81909](https://github.com/WordPress/gutenberg/pull/81909)).
 
 ### 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/icons/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Enhancements
+
+-   Add optional `keywords` to the icon manifest, giving each public icon extra search terms, and emit them from the generated `manifest.php`. The manifest is now the single source of these terms: the Storybook icon library reads them from it instead of keeping its own list, and the icons it had keywords for carry them in the manifest. ([#82367](https://github.com/WordPress/gutenberg/pull/82367))
+
 ### Breaking Changes
 
 -   A further 236 icons are now stroke-based. Use CSS `color` rather than `fill` to recolor them. ([#82540](https://github.com/WordPress/gutenberg/pull/82540), [#82754](https://github.com/WordPress/gutenberg/pull/82754))
@@ -99,7 +103,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

@@ -54,6 +54,7 @@ To add a new icon to the library, follow these steps:
      - Omit the field to keep the icon in the JS library only. It is not shipped to core.
      - `true` ships the icon to core and exposes it through the SVG Icons API, which makes it selectable in the Icon block.
      - `false` ships the icon to core and registers it for server-side use through `wp_get_icon()`, but hides it from the REST API and the Icon block. Use this for icons that belong to the admin UI rather than to post content, such as admin menu icons.
+   - `keywords` (optional): An array of lowercase search terms for the icon, such as `[ "hamburger", "navigation" ]` for Menu. Public and non-public icons alike may have them: the icons registry and the icon library match them alongside the name and label, and so does the Storybook icon library, which reads this manifest rather than keeping its own list. Terms for public icons are localized in the generated `manifest.php`.
 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,9 +46,22 @@ function generatePHPArray( manifest ) {
 		const publicEntry =
 			item.public === false ? "\n\t\t'public'   => false," : '';
 
+		// 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 }',${ publicEntry }
+		'filePath' => '${ filePath }',${ publicEntry }${ keywords }
 	),`;
 	} );