You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In the same idea of #16480, #16481 or #16482 (improvements of button block), maybe we could think about adding a suffix/prefix icon to the button label ?
Has there been some new discussions about icons in Button block recently? The "button with icon" component is very very very common in UIs and has been for years. Currently there is no simple way for users to do that without installing a plugin. Why?
Has there been some new discussions about icons in Button block recently? The "button with icon" component is very very very common in UIs and has been for years. Currently there is no simple way for users to do that without installing a plugin. Why?
As @mtias mentioned #16484 goes first but it's true there hasn't been any update about it for a while 😔
Problem is that there is currently no way to do this in other way than inline image, a feature that seems to have been completely forgotten because it's all broken.
Apart from the very obvious bugs (see my just posted issue #45664), the inline image does not behave like an image block that would be contained inside the button which is, I think, the expected behavior. That prevents for example to use .svg images on a WP install where they are reauthorized.
Another way would be to have custom html block inside a button block to include the svg code of an icon.. which is also impossible.
However the Icon Block situation happens to be resolved, I wonder if the two use cases could not be easier ways to implement a "icon button" in the current state of things.
Coming over from my duplicate request, which was merged into this issue, happy to consolidate the discussion here, as the spirit of both is the same.
What's changed since this issue was opened
When this was created in 2019, there was no core Icon block. That's no longer the case: we now have an established Icon block with its own API and icon library, and it has continued to receive enhancements in recent Gutenberg releases. The main building block for this feature already exists in core, what's missing is the ability to combine it with the Button block.
The use case
Icons inside buttons are a staple of modern interface design. Common patterns include:
A lock icon on a "Log in" button
A cart or bag icon on "Buy now" / "Add to cart"
An arrow on "See pricing" or "Get started" calls to action
These act as visual cues that reinforce a button's purpose, they're near-universal in marketing, pricing, and checkout flows. Right now this pattern is impossible with core blocks alone, it requires custom workarounds, or third-party block plugins.
Suggested direction
With the Icon block and its API now established, two approaches seem viable:
Allow the Icon block as inner content of the Button block, with controls for placement (before/after the label) and spacing between icon and text.
Add an icon setting to the Button block itself, reusing the Icon block's picker/library, with a position control for prefix or suffix placement.
Either way, a native solution would inherit button text color and scale with font size, keeping the pattern consistent with theme styles and accessible to non-developers.
Given the groundwork is now in place, it would be great to see this move forward. Happy to help with testing or feedback on any proposed implementation.
I would be cautious about adding a dedicated leading/trailing icon feature directly to core/button, at least in its current form.
Despite its name, the Button block renders an <a> element rather than a semantic <button>. That makes it suitable for calls to action and navigation, but less useful for many actual UI button patterns such as opening dialogs, toggling interfaces, submitting actions, or controlling application state.
Adding a specialized icon API to core/button could also make it harder for themes and plugins to build semantic <button> components that inherit the visual styles of the core Button block. We may end up coupling the icon implementation to the link-based block while real button controls need to reproduce or work around it separately.
There is also a design-system concern. The current Icon API is SVG-based. Until consumers can choose between different icon rendering systems—such as registered SVG collections, icon fonts, or another extensible representation—embedding a prescribed SVG icon structure into the Button block may unnecessarily constrain theme-level customization.
I am not opposed to icon-and-label controls as a UI pattern. I would prefer a more composable solution, for example:
a shared icon-label component or block composition that both <a> and <button> implementations can consume;
allowing an Icon block alongside text without making the implementation specific to core/button;
or first introducing a semantic core button/control block, distinct from the current link-based Button block.
So my concern is less about whether buttons should support icons, and more about attaching the feature specifically to a block whose underlying semantics are links.
I think the existing inline SVG icons already used by Core blocks should be integrated into the Icon Registry first. #81225
I said earlier that the Button block renders an <a> rather than a semantic <button>. That is out of date and I should have checked before writing it: tagName has accepted button since PR #54206, and the HTML element control has been in the Advanced panel since PR #70139. The semantics objection I raised does not apply — one icon slot here would serve both renderings, which makes the case for adding it stronger rather than weaker.
The other half of my comment was about the icon API being SVG-based and constraining themes. I still think there is something to settle there, but it is not really a core/button question, so I have opened it separately rather than continue it here:
#82700 — Define a state-aware icon reference contract for blocks
The short version: whether an icon attribute needs one reference or two is decided by the icon source rather than by the block, because a registered icon is one SVG with no variant axis. A single-reference attribute works for a variable icon font and renders nothing for the second state on the registry path. core/accordion-heading already runs into this and solves it by rotating a literal + 45°, which works only for that one glyph.
That issue includes a working reference implementation of the markup contract, so if icons do land here, there is something concrete to argue against.
Hi there,
when you consider this please make sure you allow also for a button to be only an icon and the label can be empty or only shows for screen reader users, as sometimes you just want an icon button and no label on it.
It treats an icon-only button as a distinct component from a text Button with a leading/trailing icon. The visible content is only the icon, while the accessible name remains in ".screen-reader-text":
Activity
mtias commentedon Jul 14, 2019
Agree this would be cool. We probably want to see where #16484 goes first.
deborah86 commentedon Aug 6, 2021
I am surprised this feature has not been added yet and it hasn't gotten any traction.
Julianoe commentedon Nov 9, 2022
Has there been some new discussions about icons in Button block recently? The "button with icon" component is very very very common in UIs and has been for years. Currently there is no simple way for users to do that without installing a plugin. Why?
Jabe64 commentedon Nov 9, 2022
As @mtias mentioned #16484 goes first but it's true there hasn't been any update about it for a while 😔
Julianoe commentedon Nov 9, 2022
Problem is that there is currently no way to do this in other way than inline image, a feature that seems to have been completely forgotten because it's all broken.
Apart from the very obvious bugs (see my just posted issue #45664), the inline image does not behave like an image block that would be contained inside the button which is, I think, the expected behavior. That prevents for example to use .svg images on a WP install where they are reauthorized.
Another way would be to have custom html block inside a button block to include the svg code of an icon.. which is also impossible.
However the Icon Block situation happens to be resolved, I wonder if the two use cases could not be easier ways to implement a "icon button" in the current state of things.
sathwikprabhu commentedon Jul 25, 2025
I use this as of now: https://github.com/ndiego/enable-button-icons
eirichmond commentedon Aug 4, 2026
Coming over from my duplicate request, which was merged into this issue, happy to consolidate the discussion here, as the spirit of both is the same.
What's changed since this issue was opened
When this was created in 2019, there was no core Icon block. That's no longer the case: we now have an established Icon block with its own API and icon library, and it has continued to receive enhancements in recent Gutenberg releases. The main building block for this feature already exists in core, what's missing is the ability to combine it with the Button block.
The use case
Icons inside buttons are a staple of modern interface design. Common patterns include:
These act as visual cues that reinforce a button's purpose, they're near-universal in marketing, pricing, and checkout flows. Right now this pattern is impossible with core blocks alone, it requires custom workarounds, or third-party block plugins.
Suggested direction
With the Icon block and its API now established, two approaches seem viable:
Either way, a native solution would inherit button text color and scale with font size, keeping the pattern consistent with theme styles and accessible to non-developers.
Given the groundwork is now in place, it would be great to see this move forward. Happy to help with testing or feedback on any proposed implementation.
Jiwoon-Kim commentedon Aug 6, 2026
I would be cautious about adding a dedicated leading/trailing icon feature directly to
core/button, at least in its current form.Despite its name, the Button block renders an
<a>element rather than a semantic<button>. That makes it suitable for calls to action and navigation, but less useful for many actual UI button patterns such as opening dialogs, toggling interfaces, submitting actions, or controlling application state.Adding a specialized icon API to
core/buttoncould also make it harder for themes and plugins to build semantic<button>components that inherit the visual styles of the core Button block. We may end up coupling the icon implementation to the link-based block while real button controls need to reproduce or work around it separately.There is also a design-system concern. The current Icon API is SVG-based. Until consumers can choose between different icon rendering systems—such as registered SVG collections, icon fonts, or another extensible representation—embedding a prescribed SVG icon structure into the Button block may unnecessarily constrain theme-level customization.
I am not opposed to icon-and-label controls as a UI pattern. I would prefer a more composable solution, for example:
<a>and<button>implementations can consume;core/button;I currently use the core Button styles for semantic
<button>controls in dialog components, which illustrates the distinction: https://designbusan.ai.kr/showcase/plugins/dialogs/So my concern is less about whether buttons should support icons, and more about attaching the feature specifically to a block whose underlying semantics are links.
I think the existing inline SVG icons already used by Core blocks should be integrated into the Icon Registry first.
#81225
Jiwoon-Kim commentedon Sep 9, 2026
A short follow-up, with one correction.
I said earlier that the Button block renders an
<a>rather than a semantic<button>. That is out of date and I should have checked before writing it:tagNamehas acceptedbuttonsince PR #54206, and the HTML element control has been in the Advanced panel since PR #70139. The semantics objection I raised does not apply — one icon slot here would serve both renderings, which makes the case for adding it stronger rather than weaker.The other half of my comment was about the icon API being SVG-based and constraining themes. I still think there is something to settle there, but it is not really a
core/buttonquestion, so I have opened it separately rather than continue it here:#82700 — Define a state-aware icon reference contract for blocks
The short version: whether an
iconattribute needs one reference or two is decided by the icon source rather than by the block, because a registered icon is one SVG with no variant axis. A single-reference attribute works for a variable icon font and renders nothing for the second state on the registry path.core/accordion-headingalready runs into this and solves it by rotating a literal+45°, which works only for that one glyph.That issue includes a working reference implementation of the markup contract, so if icons do land here, there is something concrete to argue against.
landwire commentedon Sep 9, 2026
Hi there,
when you consider this please make sure you allow also for a button to be only an icon and the label can be empty or only shows for screen reader users, as sometimes you just want an icon button and no label on it.
Jiwoon-Kim commentedon Sep 9, 2026
@landwire
I made a small reference implementation for exactly this case:
https://jiwoon-kim.github.io/axismundi/styleguide/components/icon-buttons/
It treats an icon-only button as a distinct component from a text Button with a leading/trailing icon. The visible content is only the icon, while the accessible name remains in ".screen-reader-text":
The demo also covers toggle/non-toggle states, sizing, width variants, and target size.
If "core/icon-button" is ever considered separately from adding icons to "core/button", this could be a useful markup reference.