UI: add LinkButton by simison · Pull Request #78944 · WordPress/gutenberg

simison · 2026-06-04T12:18:14Z

What?

Resolves #77098

Adds LinkButton component to UI package, following most of the visual features of Button.
Adds guidance on when to choose Button, Link, or LinkButton.
Supports icons via LinkButton.Icon component, which is just re-export of ButtonIcon

Does not support:

openInNewTab like Link (good for a follow-up)
Semantic props relevant to "real" buttons (nativeButton, loadingAnnouncement, loading, focusableWhenDisabled, disabled and aria-pressed).

Link button behaves visually like Button, but accepts href and semantically behaves like Link.

The component has its own defence styles, instead of re-using a defence. Otherwise, we'd see incorrect text colors;

Why?

In principle, we'd prefer people use Link for actual links, and Button for non-links. In practise, these expectations are blurred lines for both designers and users, and sometimes even React apps (including Gutenberg) have internal, in-app flows which require using href instead of onClick.

In the guidance added in this PR we're still encouraging people to choose Button or Link over LinkButton, and explain user expectations.

How?

Testing Instructions

See Storybook guide added under Button /?path=/docs/design-system-components-button-usage-guidelines--docs
See component from storybook /?path=/docs/design-system-components-linkbutton--docs

Testing Instructions for Keyboard

Use of AI Tools

github-actions · 2026-06-04T12:28:02Z

Size Change: +687 B (+0.01%)

Total Size: 8.21 MB

📦 View Changed

Filename	Size	Change
`build/modules/boot/index.min.js`	51.9 kB	+80 B (+0.15%)
`build/modules/content-types/index.min.js`	158 kB	+266 B (+0.17%)
`build/scripts/block-editor/index.min.js`	379 kB	+86 B (+0.02%)
`build/scripts/block-library/index.min.js`	324 kB	+57 B (+0.02%)
`build/scripts/edit-site/index.min.js`	296 kB	+145 B (+0.05%)
`build/scripts/editor/index.min.js`	463 kB	+54 B (+0.01%)
`build/scripts/media-utils/index.min.js`	113 kB	-1 B (0%)

_{compressed-size-action}

github-actions · 2026-06-04T12:52:11Z

Flaky tests detected in 45696b0.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/26951289449
📝 Reported issues:

[Flaky Test] should paste block styles using keyboard #78759 in /test/e2e/specs/editor/various/list-view.spec.js
[Flaky Test] shouldn't conflict with server-side autosave #78706 in /test/e2e/specs/editor/various/autosave.spec.js

github-actions · 2026-06-05T13:17:32Z

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 props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: simison <simison@git.wordpress.org>
Co-authored-by: jameskoster <jameskoster@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

simison · 2026-06-05T13:33:15Z

Users can now use icons by using Button.Icon:

<LinkButton href="#">
    <Button.Icon icon={ <svg /> } />
    Link
</LinkButton>

~~...is that ok, or should we have LinkButton.Icon and basically re-export Button.Icon?~~

Edit: there's now LinkButton.Icon

jameskoster · 2026-06-05T14:03:23Z

Should this support openInNewTab?

jameskoster · 2026-06-05T14:05:24Z

I could potentially see this being used in the Site Editor sidebar which makes me wonder if it should support a 'selected' state, or would that be a property of a higher-level menu component?

This reverts commit 6c12505.

simison · 2026-06-05T16:39:05Z

Should this support openInNewTab?

Possibly; just not sure how we should go about the icon in that case (since buttons can have icons by other methods), so I left it for a separate PR to get this in sooner as-is without the support for now.

simison · 2026-06-05T16:40:52Z

I could potentially see this being used in the Site Editor sidebar which makes me wonder if it should support a 'selected' state, or would that be a property of a higher-level menu component?

Easy enough to add later when it is used there, rather than hypothetically ahead of time. :-)

ciampo · 2026-06-05T17:22:11Z

I could potentially see this being used in the Site Editor sidebar which makes me wonder if it should support a 'selected' state, or would that be a property of a higher-level menu component?

LinkButton should be used for links that look like buttons. In that sense, selected isn't really a quality of a link, while it can be associated with a button (pressed) or a checkbox / radio menu item (checked)

simison · 2026-06-05T20:19:14Z

+ * A link that looks like a `Button`. Prefer `Link` for navigation unless
+ * button prominence is intentional.


Could be a bit more generic and less forward about Link here. 😅

ciampo

Thank you for working on this!

ciampo · 2026-06-05T17:23:22Z

+Choose the component based on **what happens when the user activates it**, not
+only on how it should look.


Nit: I don't think we normally break the line in markdown files for formatting reasons?

Suggested change

Choose the component based on **what happens when the user activates it**, not

only on how it should look.

Choose the component based on **what happens when the user activates it**, not only on how it should look.

Here and everywhere else applicable in the PR

ciampo · 2026-06-05T17:24:41Z

+<Markdown>{`
+| Goal | Component | Element | Examples |
+| --- | --- | --- | --- |
+| Change something on the current page | [Button](?path=/docs/design-system-components-button--docs) | \`<button>\` | Save, Delete, Open dialog, Toggle |


ciampo · 2026-06-05T17:28:59Z

@@ -0,0 +1,18 @@
+@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;
+
+@layer wp-ui-components {


Not sure if we should use the compositions layer here, since we technically want to make sure these styles win over Button styles. Also in relationship to #78953

ciampo · 2026-06-05T21:17:09Z

+.link-button,
+.link-button:is(:hover, :focus, :active, :visited) {
+	outline: var(--_gcd-link-button-outline, 0 solid transparent);
+	color: var(--_gcd-link-button-color, inherit);
+	box-shadow: var(--_gcd-link-button-box-shadow, none);
+	border-radius: var(--_gcd-link-button-border-radius, 0);
+	transition: var(--_gcd-link-button-transition, none);
+	text-decoration: var(--_gcd-link-button-text-decoration, none);
+}


Some of these new gdc variables are not being set, causing the focus ring is currently invisible, and the Button's border radius is not applied.

I played with these variables locally, and this seems to work well

diff --git i/packages/ui/src/link-button/link-button.tsx w/packages/ui/src/link-button/link-button.tsx index e68ed654e49..97381ea931e 100644 --- i/packages/ui/src/link-button/link-button.tsx +++ w/packages/ui/src/link-button/link-button.tsx @@ -29,10 +29,10 @@ export const LinkButton = forwardRef< HTMLAnchorElement, LinkButtonProps >( ) { const mergedClassName = clsx( defenseStyles[ 'link-button' ], - styles[ 'link-button' ], resetStyles[ 'box-sizing' ], focusStyles[ 'outset-ring--focus-except-active' ], variant !== 'unstyled' && buttonStyles.button, + variant !== 'unstyled' && styles[ 'link-button' ], buttonStyles[ `is-${ tone }` ], buttonStyles[ `is-${ variant }` ], buttonStyles[ `is-${ size }` ], diff --git i/packages/ui/src/link-button/style.module.css w/packages/ui/src/link-button/style.module.css index 3ed7f450998..af7b72025c1 100644 --- i/packages/ui/src/link-button/style.module.css +++ w/packages/ui/src/link-button/style.module.css @@ -6,6 +6,15 @@ global CSS defense. */ --_gcd-link-button-color: var(--wp-ui-button-foreground-color); --_gcd-link-button-text-decoration: none; + --_gcd-link-button-border-radius: var(--wpds-border-radius-sm); + + /* Extend the focus utility's outline transition (set in + `focus.module.css`) with a `color` transition, so styled variants fade + their foreground like `Button`. The `unstyled` variant omits this class + and falls back to the utility's outline-only transition. */ + @media not ( prefers-reduced-motion ) { + --_gcd-link-button-transition: color 0.1s ease-out, outline 0.1s ease-out; + } &:visited { --_gcd-link-button-color: var(--wp-ui-button-foreground-color); diff --git i/packages/ui/src/utils/css/focus.module.css w/packages/ui/src/utils/css/focus.module.css index b8834f98bbd..57d8bd2bd0b 100644 --- i/packages/ui/src/utils/css/focus.module.css +++ w/packages/ui/src/utils/css/focus.module.css @@ -10,6 +10,7 @@ .outset-ring--focus-parent-visible { @media not ( prefers-reduced-motion ) { --_gcd-a-transition: outline 0.1s ease-out; + --_gcd-link-button-transition: outline 0.1s ease-out; transition: outline 0.1s ease-out; } @@ -29,6 +30,7 @@ :focus-visible .outset-ring--focus-parent-visible { --_gcd-a-outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand); --_gcd-div-outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand); + --_gcd-link-button-outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand); outline: var(--wpds-border-width-focus) solid var(--wpds-color-stroke-focus-brand); }

ciampo · 2026-06-05T21:19:44Z

+
+export type { LinkButtonProps, LinkButtonIconProps } from './types';
+
+ButtonIcon.displayName = 'LinkButton.Icon';


This line is actually overriding the displayName set originally on the component (ie. Button.Icon).

We should probably create a separate, thin wrapper component.

ciampo · 2026-06-05T21:23:09Z

+| --- | --- | --- | --- |
+| Change something on the current page | [Button](?path=/docs/design-system-components-button--docs) | \`<button>\` | Save, Delete, Open dialog, Toggle |
+| Navigate to another page or URL | [Link](?path=/docs/design-system-components-link--docs) | \`<a>\` | "Learn more", docs links, external references |
+| Navigate with button styling | [LinkButton](?path=/docs/design-system-components-link-button--docs) | \`<a>\` | Standalone CTAs, card actions |


ciampo · 2026-06-05T21:23:38Z

+> control. Reach for `LinkButton` only when you have considered `Button` and
+> `Link` and still need button prominence.
+
+See [LinkButton](?path=/docs/design-system-components-link-button--docs) for API


The URL generated by Storybook doesn't have the hyphen

Suggested change

See [LinkButton](?path=/docs/design-system-components-link-button--docs) for API

See [LinkButton](?path=/docs/design-system-components-linkbutton--docs) for API

mirka

Sorry I didn't have time to run the code or ask my questions to an agent first, but wrote down my initial thoughts 😄 Thanks for working on this!

mirka · 2026-06-05T22:41:15Z

+		componentStatus: {
+			status: 'use-with-caution',
+			whereUsed: 'global',
+			notes: 'Not yet recommended for use alongside components from `@wordpress/components`, pending review of style consistency with `@wordpress/components` and text overflow behavior. See [WordPress/gutenberg#76135](https://github.com/WordPress/gutenberg/issues/76135).',


Is this duplication necessary?

mirka · 2026-06-05T22:43:39Z

+		docs: {
+			description: {
+				component:
+					'See [Usage Guidelines](?path=/docs/design-system-components-button-usage-guidelines--docs) for when to use `Button`, `Link`, or `LinkButton`.',
+			},
+		},


Ideally, this kind of description should be consolidated with the main component's JSDoc description so it's reusable everywhere including IntelliSense, not just Storybook.

mirka · 2026-06-05T22:52:23Z

+			className
+		);
+
+		const element = useRender( {


Curious, did we consider composing from the Link component, rather than building from scratch? I see there's even an unstyled variant for this kind of purpose. Not sure if that's a good idea, but good to think about the pros/cons nonetheless.

mirka · 2026-06-05T22:55:00Z

 * A styled anchor element with support for semantic color tones and an
 * unstyled escape hatch.
+ *
+ * @see {@link https://wordpress.github.io/gutenberg/?path=/docs/design-system-components-button-usage-guidelines--docs When to use Button, Link, or LinkButton}


Related to my previous comment about consolidating component descriptions, and not sure if this still holds true in the latest version of Storybook, but @ tags in JSDoc tend to be dropped the docgen, so we've been preferring to write everything without these tags.

mirka · 2026-06-05T23:01:52Z

+/* Anchor elements styled as buttons (`LinkButton`). Separate from `.a` because
+   button foreground colors differ from link colors. */
+.link-button,
+.link-button:is(:hover, :focus, :active, :visited) {


The component has its own defence styles, instead of re-using a defence. Otherwise, we'd see incorrect text colors;

Not sure I understand why though? We can't just set --_gcd-a-color to the correct color in the component stylesheet?

Ideally this defense module stylesheet knows nothing about our specific components, only the raw elements/selectors that we're defending against.

simison added the [Status] In Progress Tracking issues with work in progress label Jun 4, 2026

github-actions Bot added [Package] UI /packages/ui and removed [Status] In Progress Tracking issues with work in progress labels Jun 4, 2026

simison changed the title ~~UI: add link button~~ UI: add LinkButton Jun 4, 2026

simison force-pushed the add/ui-linkbutton branch from 45696b0 to 92c1cd0 Compare June 5, 2026 12:20

simison marked this pull request as ready for review June 5, 2026 13:17

simison requested a review from a team as a code owner June 5, 2026 13:17

simison added the [Type] Enhancement A suggestion for improvement. label Jun 5, 2026

jameskoster reviewed Jun 5, 2026

View reviewed changes

Comment thread packages/ui/src/link-button/types.ts Outdated

simison added 10 commits June 5, 2026 19:34

UI: add link button

64c2c75

Update CHANGELOG.md

9f23b0f

Add guidance

2cceabf

Update guidelines

2ed5181

Update guidance copy

745591b

Fix quick reference table

06302c3

Fix leaking defence style

0df33c4

Revert "Fix leaking defence style"

0777eca

This reverts commit 6c12505.

Add LinkButton defence style

582fbd7

Remove disabled state

6aa67da

simison force-pushed the add/ui-linkbutton branch from f5b5d76 to 6aa67da Compare June 5, 2026 16:37

Update style.module.css

3e44d0d

ciampo assigned simison Jun 5, 2026

simison commented Jun 5, 2026

View reviewed changes

ciampo reviewed Jun 5, 2026

View reviewed changes

mirka reviewed Jun 5, 2026

View reviewed changes

		* A link that looks like a `Button`. Prefer `Link` for navigation unless
		* button prominence is intentional.

		Choose the component based on what happens when the user activates it, not
		only on how it should look.

	\| Change something on the current page \| [Button](?path=/docs/design-system-components-button--docs) \| \`<button>\` \| Save, Delete, Open dialog, Toggle \|
	\| Performs an action on the current page. \| [Button](?path=/docs/design-system-components-button--docs) \| \`<button>\` \| Save, Delete, Submit, Open dialog, Toggle \|

		@@ -0,0 +1,18 @@
		@layer wp-ui-utilities, wp-ui-components, wp-ui-compositions, wp-ui-overrides;

		@layer wp-ui-components {


		export type { LinkButtonProps, LinkButtonIconProps } from './types';

		ButtonIcon.displayName = 'LinkButton.Icon';

	\| Navigate with button styling \| [LinkButton](?path=/docs/design-system-components-link-button--docs) \| \`<a>\` \| Standalone CTAs, card actions \|
	\| Navigate with button styling \| [LinkButton](?path=/docs/design-system-components-linkbutton--docs) \| \`<a>\` \| Standalone CTAs, card actions \|

	See [LinkButton](?path=/docs/design-system-components-link-button--docs) for API
	See [LinkButton](?path=/docs/design-system-components-linkbutton--docs) for API

Conversation

simison commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Testing Instructions for Keyboard

Use of AI Tools

Uh oh!

github-actions Bot commented Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jun 4, 2026

Uh oh!

github-actions Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simison commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

jameskoster commented Jun 5, 2026

Uh oh!

jameskoster commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

simison commented Jun 5, 2026

Uh oh!

simison commented Jun 5, 2026

Uh oh!

ciampo commented Jun 5, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ciampo left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mirka left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

simison commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 4, 2026 •

edited

Loading

github-actions Bot commented Jun 5, 2026 •

edited

Loading

simison commented Jun 5, 2026 •

edited

Loading

jameskoster commented Jun 5, 2026 •

edited

Loading