FormTokenField: Match labels in suggestions instead of keys when searching for values#74772
Open
FormTokenField: Match labels in suggestions instead of keys when searching for values#74772
Conversation
elazzabi
requested review from
ajitbohra,
gigitux,
ntsekouras and
oandregal
as code owners
github-actions
bot
added
[Package] Components
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
elazzabi
changed the title
oandregal
added
[Type] Enhancement
oandregal
reviewed
Jan 21, 2026
Member
|
I've noticed the array's render method is using the key, not the label, even though it has elements. I expected "array with elements" to render "Item 1, Item 2, Item 3" instead of "a, b, item3". 
Would you be able to look at that as well? |
oandregal
reviewed
Jan 21, 2026
Member
Member
|
The direction looks good to me, I've just shared a few tweaks. Pinging @WordPress/gutenberg-components in case component folks have other thoughts. |
…array and arrayWithElements fields
…g in RenderFromElements
Contributor
Author
@oandregal I believe that's the current behavior? I see that the keys are displayed (item1, item2) instead of the elements (Item 1, Item 2). 
I pushed the changes in 2d3a6c7, but just wanted to raise it, given this will be a "breaking change" from how it was displayed before. |
Contributor
Author
oandregal
approved these changes
Jan 22, 2026
Member
oandregal
left a comment
oandregal
left a comment
There was a problem hiding this comment.
It's working nicely, thank you!
Member
|
The CI failure is due to the missing dataviews/changelog |
Contributor
Author
|
Thank you, @oandregal, for the review. I added this changelog for dataviews, let me know if it makes sense 7e6174b |
ntsekouras
previously requested changes
Jan 23, 2026
Contributor
ntsekouras
left a comment
ntsekouras
left a comment
There was a problem hiding this comment.
Please don't merge yet. I'm writing a comment.
ntsekouras
reviewed
Jan 23, 2026
|
|
||
| _suggestions.forEach( ( suggestion ) => { | ||
| const index = suggestion | ||
| const normalizedSuggestionKey = suggestion |
Contributor
There was a problem hiding this comment.
I'm always wary about changing reusable components, so here are my thoughts.
Right now consumers that work with ids but want to have different labels provided, usually pass as suggestions the user friendly label and have to go back and forth about extracting the id based on the selected suggestion. An example is author control in Query Loop
.
This PR would enable a simpler handling for such cases by getting the actual id as value and have a simple onChange and so on.
I get the use case provided with the countries (US: 'United States', ) and essentially the short US is kind of the id. The main difference though is that these shortcodes act as ids but are already more user friendly than numeric ids.
So, how this change could be useful for other consumers too (like the author control I shared above)? Probably by having an extra prop to that component like matchKey=false for cases where we want a simplified handling of ids, but no matching of the keys.
Member
There was a problem hiding this comment.
I wonder if labels should be the only thing that are checked, basically inverting the current behavior. If I follow, this would address the original issue of the pull request and avoid the need for hacks in the author control, which seem to have been implemented to work around the existing behavior. I'm not sure if there's context for why it was implemented the way it was, but to me it seems confusing as a user if I were to see filtered results that may not necessarily have anything to do with the label that I see.
Contributor
Author
There was a problem hiding this comment.
but to me it seems confusing as a user if I were to see filtered results that may not necessarily have anything to do with the label that I see.
@aduth I completely agree! I don't have context about the original implementation either, but swapping the ids with labels will definitely fix the original issue. If everyone is on board, I can adapt the PR.
Member
There was a problem hiding this comment.
After doing a bit of digging, I feel pretty confident that matching only against what's shown to the user (after displayTransform if given) should be the expected behavior. As mentioned previously, this aligns to the user's expectation of searching against what they see.
As far as context, it looks like this was never really an explicit decision. The original implementation in #924 only introduced displayTransform to deal with character encoding, so it likely wasn't as pressing a concern which of the key or displayed labels was searched, since they were mostly in alignment. The idea of using "mappings" between internal value representations and user-displayed labels was added later, but we never revisited the search behavior.
I could imagine an argument that searching "US" should produce "United States", but (a) I don't really think it should, and (b) if it did, it should do so based on a fuzzy search of [U]nited [S]tates and not because of whatever the internal value happens to be. If someone really wanted this behavior, it seems reasonable to me that they could provide those searchable abbreviations in the label, e.g. "United States (US)".
Member
There was a problem hiding this comment.
matching only against what's shown to the user (after
displayTransformif given) should be the expected behavior
I agree. But considering back compat and the fact that we'll likely have a @wordpress/ui replacement for this component (#74178) within the month, we can probably leave FormTokenField as is?
Member
There was a problem hiding this comment.
Maybe. Personally I feel like the current behavior is rather buggy and unexpected, and the fix relatively straightforward. @elazzabi Was this pull request based on a present need from a use-case you have?
Contributor
Author
There was a problem hiding this comment.
@aduth yes. I'm using the component in WooCommerce, and selecting a country is one of the first implementations. For now, United States (for example) is only showing with US, which is not ideal.
Member
There was a problem hiding this comment.
In that case, I personally feel we could move forward with the changes to search only the resulting label.
As far as backwards-compatibility, we should describe the updated behavior, though I'd hesitate to call it a breaking change, would even lean toward bug fix if anything. Looking at existing usage and in the plugin repository, I don't believe that current usage in Gutenberg would be affected. It could be worth going through some of the top hits in the plugin repository (e.g. WooCommerce, which you may be more attuned to already @elazzabi ).
Contributor
Author
There was a problem hiding this comment.
I agree that it makes more sense to search for labels, at least, that's what shows to the user. I updated the PR to match only the label.
As far as backwards-compatibility, we should describe the updated behavior, though I'd hesitate to call it a breaking change, would even lean toward bug fix if anything.
I added the changes to the "bug fixes" part in the changelog 593a00a. Let me know if this needs to be in a different place.
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Flaky tests detected in 0fd48ab. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/21281143193
|
elazzabi
changed the title
|
Size Change: +53 B (0%) Total Size: 3.03 MB
ℹ️ View Unchanged
|
aduth
reviewed
Feb 10, 2026
Comment on lines
+80
to
+82
| if ( indexOfMatch < 0 ) { | ||
| return null; | ||
| } |
Member
There was a problem hiding this comment.
What scenario is this new condition meant to handle?
Contributor
Author
There was a problem hiding this comment.
I added this as an early fail mechanism. Otherwise, the subsequent check will be:
transformedSuggestion.substring(
0,
-1
)Which might produce weird results.
Member
There was a problem hiding this comment.
Right, but when would that actually happen, and why wasn't it a problem before?
Contributor
Author
There was a problem hiding this comment.
Hmmm, this would trigger when there is no match. I only added it because I thought it made sense, but it's true that it wasn't there before, and there were no known side effects. So let's drop it (cc1190b)
Member
There was a problem hiding this comment.
Yeah, this would be a good example of a thing where it'd be good to have regression testing coverage covering the scenario if it were in-fact an issue.
aduth
approved these changes
Feb 12, 2026
Member
aduth
left a comment
aduth
left a comment
There was a problem hiding this comment.
I think this looks good on the FormTokenField side of things 👍
Comment on lines
+80
to
+82
| if ( indexOfMatch < 0 ) { | ||
| return null; | ||
| } |
Member
There was a problem hiding this comment.
Right, but when would that actually happen, and why wasn't it a problem before?
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add support for matching both the key and label in
FormTokenFieldsuggestions.For country suggestions, the options are as follows:
Currently, searching for "united" doesn't return any results (given that suggestions only match 'US' and 'UK')
Why
Users expect label-based matching to surface suggestions when display values differ from raw values.
How
Normalize suggestion values and display labels, then compare both when building the suggestion buckets.
Testing
In the DataViews array field story, confirm searching by
aandbentries, in addition toitem