Problem/Motivation
In Drupal 11.1, we have shipped #3471494: Add an icon management API without a Form Element in order to test what can be done in contrib first.
We have now 2 form elements built on the Icon API in contrib, from the same module. Other modules implements the Core Icon API but they don't provide (yet) a dedicated Form Element.
icon_autocomplete
Properties:
- #default_value: (string) Icon value as pack_id:icon_id.
- #show_settings: (bool) Enable extractor settings, default FALSE.
- #default_settings: (array) Settings for the extractor settings.
- #settings_title: (string) Extractor settings details title.
- #allowed_icon_pack: (array) Icon pack to limit the selection.
- #return_id: (bool) Form return icon id instead of icon object as default.
Some base properties from FormElementBase:
- #description: (string) Help or description text for the input element.
- #placeholder: (string) Placeholder text for the input, default to 'Start typing icon name'.
- #required: (bool) Whether or not input is required on the element.
- #size: (int): Textfield size, default 55.
Example:
[
'#type' => 'icon_autocomplete',
'#title' => $this->t('Select icon'),
'#default_value' => 'my_icon_pack:my_default_icon',
'#allowed_icon_pack' => [
'my_icon_pack',
'other_icon_pack',
],
'#show_settings' => TRUE,
];
icon_picker
Properties:
- #default_value: (string) Icon value as pack_id:icon_id.
- #show_settings: (bool) Enable extractor settings, default FALSE.
- #default_settings: (array) Settings for the extractor settings.
- #settings_title: (string) Extractor settings details title.
- #allowed_icon_pack: (array) Icon pack to limit the selection.
- #return_id: (bool) Form return icon id instead of icon object as default.
Some base properties from FormElementBase.
- #description: (string) Help or description text for the input element.
- #placeholder: (string) Placeholder text for the input, default to 'Click to select an Icon'.
- #required: (bool) Whether or not input is required on the element.
- #size: (int): Textfield size, default 55.
Global properties applied to the parent element:
- #attributes': (array) Attributes to the global element.
Example:
[
'#type' => 'icon_picker',
'#title' => $this->t('Select icon'),
'#default_value' => 'my_icon_pack:my_default_icon',
'#allowed_icon_pack' => [
'my_icon_pack',
'other_icon_pack',
],
'#show_settings' => TRUE,
];
Other form elements to study
They are not implementing (yet) the Icon API:
- iconset : IconsetSelector
- icons: IconSelect
- ex_icons : ExIconSelect
- micon (icomoon) : Micon
- md_fontello : MDIcon
- iconify_field : IconifyField
They are already implementing the Icon API but not at the Form Element level:
- iconify_icons : IconifyIcons
Proposed resolution
Add a Form Element for the icon API in Core, maybe inspired by one of those examples.
If possible, let's keep it simple, dependency free, and theme agnostic.
Also, let's notice the Form Elements may be impacted by #3508641: Define form elements from SDC the next months/years, so let's manage the callbacks in a way we can move to SDC later.
User interface changes
No, the form element is not used by default in Druapl Core. It will be available for Contrib modules (which will still be able to add their owns).
API changes
Only additions.
| Comment | File | Size | Author |
|---|---|---|---|
| #9 | icon_autocomplete.png | 10.92 KB | gxleano |
| #9 | icon_autocomplate.gif | 763.33 KB | gxleano |
Issue fork drupal-3528969
Show commands
Start within a Git clone of the project using the version control instructions.
Or, if you do not have SSH keys set up on git.drupalcode.org:
Comments
Comment #2
larowlanComment #3
pdureau commentedComment #4
pdureau commentedCurrently trying to get feedbacks from contrib module maintainers:
Comment #5
quietone commentedComment #6
mogtofu33 commentedAdded a grid view on the icon_autocomplete, it add 2 new attributes:
Could make icon_picker obsolete for now, need discussion.
Comment #9
gxleano commentedIn order to test this implementation, we would need to create a new element like:
Evidences:

Comment #10
gxleano commentedIn order to have a bunch of icons to test this new implementation, I have provide the iconsets using https://www.drupal.org/project/iconify_icons
2.0.x, in this case we would just need to:1. Enable the module
2. Go to
/admin/config/iconify_icons/settingsand select the iconsets which we would like to use.It can be even tested with core iconsets, like navigation. In this case, we would just need to enable the Navigation module and it will be available to be used in the
icon_autocompleteform elementComment #11
pdureau commentedJean, can you have a look?
Comment #12
needs-review-queue-bot commentedThe Needs Review Queue Bot tested this issue. It fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".
This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.
Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.
Comment #14
pdureau commentedComment #15
pdureau commentedRebased & squashed (the previous HEAD has been tagged
previous/3528969-add-form-elements/2026-04-2)Pipeline is red. David (@gxleano), you can assign to you if you want to check.
Comment #16
gxleano commentedSure, I will try to check this during Drupal Dev Days Athens
Comment #17
gxleano commentedComment #18
larowlanLeft some comments on the MR
Comment #19
gxleano commentedComment #20
jatingupta40 commentedComment #21
gxleano commentedThanks to think on work on this @jatingupta40!
But seems like we are almost done on review from @larowlan
Comment #22
gxleano commentedComment #23
larowlanI think this is ready now
Comment #24
pdureau commentedThat's so great. I will have a last look (by testing with 2 modules already using Icon API: UI Icons & Iconify and commit to main and 11.x.)
Comment #25
pdureau commentedTested with the #3589768: Drupal 12 compatibility branch of UI Icons.
I did this temporary change in
\Drupal\ui_icons\Element\IconAutocomplete:But the Core
icon_autocompleteform element (\Drupal\Core\Render\Element\IconAutocomplete) is always loaded instead of the contrib one anyway. At least it doesn't break.Issue about submitted value
Iconmedia source plugin: Error message: "This value should not be null."Cannot access offset of type string on string in ui_icons_menu_link_alter() (line 159 of ui_icons_menu.module).I guess it is because the value is always submitted as 'pack_id:icon_id', but in UI Icons, it is the case only when
#return_idisTRUE, but it isFALSEby default. For information,#return_idis:ui_icons_field(withicon_link_widget),ui_icons_media(in media library),ui_icons_menu(usingicon_link_widget), andui_icons_patternsui_icons_ckeditor5,ui_icons_field(withicon_widget) andui_icons_media(in entity form display)Missing settings form
The icon settings form is missing from Core form element. In UI Icons, it is displayed in
ui_icons_ckeditor5,ui_icons_field(withicon_link_widgetif the setting is TRUE),ui_icons_patternsandui_icons_menu.I understand this decision, it is to keep Core form element simple and avoid the burden of generating a form from JSON schema (something we are still figuring out for SDC). So, it is the role of contrib module like UI Icons to extend the element, adding settings management.
To review
Overriding the element is fixing both the value type issue and the missing setting form:
So UI Icons will still work after this MR is merged. That' a relief, but are we at risk of diverging from the broader Icon API ecosystem by having such divergences in our own implementation?
Jean (@mogtofu33), as both the Icon API expert and the UI Icons lead, are you OK about this MR?
Without any news late Thursday May 14th, I will put the ticket back to RTBC.
Comment #26
pdureau commentedComment #27
needs-review-queue-bot commentedThe Needs Review Queue Bot tested this issue. It no longer applies to Drupal core. Therefore, this issue status is now "Needs work".
This does not mean that the patch necessarily needs to be re-rolled or the MR rebased. Read the Issue Summary, the issue tags and the latest discussion here to determine what needs to be done.
Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.
Comment #28
gxleano commentedComment #29
gxleano commentedComment #30
mogtofu33 commentedSorry for the late reply. Some remarks on the search service, from testing the MR with UI Icons.
Ranking.
doSearch()appends matches in pack order. A substring match declared before a prefix match comes first. The exact branch compares the query with the full id, so add never matches core:add as exact.Example: 60 icons xhomex1..60 declared before home, max_result 50, home is not returned.
Drupal\ui_icons\IconSearch::doSearch() fills priority buckets instead: full id, whole words in order, whole words any order, substring in order, substring any order.
Result: best match first, independent of pack declaration order. The UI Icons data provider has 31 cases and can be ported to IconSearchTest. I can push that if ok.
Hard cap.
search()appliesmin($max_result, 200). UI Icons picker and library pass the total icon count to paginate all matches.The cap could live in the controller, and the service honors the argument.
Small fixes, let me know if i can commit or if they need discussion:
:. Spaces and any user input become the key. The database backend hashes ids over 255 characters, other backends have their own limits. hash('xxh3', ...) gives a fixed length id and keeps user input out of keys.
Optional. An IconSearchInterface would let contrib swap the ranking through a service provider. Not blocking.
Note: grammar and language fixes with help of LLM.
Comment #31
pdureau commentedComment #32
gxleano commented@mogtofu33
Thanks for the thorough review. Everything is addressed in the MR, with a few deviations noted below.
Ranking
doSearch()now scans every icon once, drops each into the first matching bucket, merges the buckets, and slices to$max_resultat the end.Two additions on top of the five buckets you listed, both from testing against
icon_test:home:widgetahead of every icon actually named home.core:home-outlineandother:my-hometied, and declaration order decided again.So the order is:
Your 31 cases are very welcome in
IconSearchTest::providerRanking(); a few expectations may shift because of the extra bucket.Hard cap
Removed from the service, which now honors any positive
$max_result. A non-positive value returns an empty array.The controller clamps the query parameter to
SEARCH_RESULT_MAX, and the constant's docblock on the interface now says exactly that: it is the bound anything exposing search to untrusted requests should apply.Small fixes
mb_strlen()applied. One correction: core'sautocomplete.jsdefaults tominLength 1and the element does not override it, so the server check is the real guard. SettingminLength 2on the element is a possible follow-up.$max_resultis no longer part of the cache ID. The full ranked list is cached once per query and pack set, and sliced on read, so varyingmax_resulton the anonymous route cannot create rows either. The pack list is sorted before hashing. The trade-off is that a cache entry holds every match for that query rather than the first page.Crypt::hashBase64()rather thanhash('xxh3'), to match AssetResolver and the cache backends.Interface
IconSearchInterfaceadded as sketched, with the three constants.IconSearchimplements it, the controller type-hints it, andcore.services.ymlaliases it toicon.search.One open question
Repeated query words ("add add") are treated as a set by the whole-word and substring "any order" buckets, but by multiplicity in the "in order" ones.
Deduplicating the query words once would make them agree. Happy to add it if you think it matters.
Note: code has been fixed with help of LLM (AI + Human in the loop).
Comment #33
gxleano commentedComment #35
mogtofu33 commentedI pushed the UI Icons search cases to IconSearchTest.
The search cache writes one permanent row per distinct query and pack list. Measured on the anonymous route:
I tested a normalized cache id: lowercase query, pack limit applied on read. Those variants then share one row. Word combinations still add rows: ar ro, ro ar, a r and ar ar create four.
Branch
3528969-drop-search-cacheremoves the result cache from IconSearch and thecache.iconbin:Repeated words: add add returns add-add first.
Generated with the help of an LLM.