Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

feat(Link): render button when href is undefined (#2507)

Cindy Zhang259eaedbb6e0
diff --git a/apps/storybook/stories/Link.stories.tsx b/apps/storybook/stories/Link.stories.tsx
index 97cf5e7327..e46377a546 100644
--- a/apps/storybook/stories/Link.stories.tsx
+++ b/apps/storybook/stories/Link.stories.tsx
@@ -129,11 +129,8 @@ export const Standalone: Story = {
export const InlineWithText: Story = {
render: () => (
<XDSText type="body">
- Read the{' '}
- <XDSLink href="/docs">
- documentation
- </XDSLink>{' '}
- for more information about using XDS components.
+ Read the <XDSLink href="/docs">documentation</XDSLink> for more
+ information about using XDS components.
</XDSText>
),
};
@@ -154,10 +151,7 @@ export const AllVariants: Story = {
<XDSLink href="/primary" color="primary" isStandalone>
Primary
</XDSLink>
- <XDSLink
- href="/secondary"
- color="secondary"
- isStandalone>
+ <XDSLink href="/secondary" color="secondary" isStandalone>
Secondary
</XDSLink>
<XDSLink href="/inherit" color="inherit" isStandalone>
@@ -165,37 +159,21 @@ export const AllVariants: Story = {
</XDSLink>
</div>
<div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>
- <XDSLink
- href="/underlined"
- hasUnderline
- isStandalone>
+ <XDSLink href="/underlined" hasUnderline isStandalone>
With underline
</XDSLink>
- <XDSLink
- href="https://example.com"
- isExternalLink
- isStandalone>
+ <XDSLink href="https://example.com" isExternalLink isStandalone>
External
</XDSLink>
- <XDSLink
- href="/tooltip"
- tooltip="Helpful info"
- isStandalone>
+ <XDSLink href="/tooltip" tooltip="Helpful info" isStandalone>
With tooltip
</XDSLink>
</div>
<div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>
- <XDSLink
- href="/disabled"
- isDisabled
- isStandalone>
+ <XDSLink href="/disabled" isDisabled isStandalone>
Disabled active
</XDSLink>
- <XDSLink
- href="/disabled"
- color="secondary"
- isDisabled
- isStandalone>
+ <XDSLink href="/disabled" color="secondary" isDisabled isStandalone>
Disabled secondary
</XDSLink>
</div>
@@ -211,16 +189,10 @@ export const ExternalLinks: Story = {
flexDirection: 'column',
gap: '8px',
}}>
- <XDSLink
- href="https://github.com"
- isExternalLink
- isStandalone>
+ <XDSLink href="https://github.com" isExternalLink isStandalone>
GitHub
</XDSLink>
- <XDSLink
- href="https://developer.mozilla.org"
- isExternalLink
- isStandalone>
+ <XDSLink href="https://developer.mozilla.org" isExternalLink isStandalone>
MDN Web Docs
</XDSLink>
<XDSLink
@@ -259,3 +231,157 @@ export const LinksWithTooltips: Story = {
</div>
),
};
+
+export const ButtonFallback: Story = {
+ args: {
+ children: 'Click me (no href)',
+ onClick: () => alert('Clicked!'),
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'When `href` is undefined, XDSLink renders a `<button>` with reset styles. ' +
+ 'Visually identical to a link, but semantically correct for actions that do not navigate.',
+ },
+ },
+ },
+};
+
+export const ButtonFallbackDisabled: Story = {
+ args: {
+ children: 'Disabled action',
+ isDisabled: true,
+ },
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'The button fallback supports the `isDisabled` prop with native `disabled` attribute.',
+ },
+ },
+ },
+};
+
+export const ButtonFallbackVariants: Story = {
+ render: () => (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '12px',
+ maxWidth: '600px',
+ }}>
+ <div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>
+ <XDSLink onClick={() => {}} isStandalone>
+ Active (default)
+ </XDSLink>
+ <XDSLink onClick={() => {}} color="primary" isStandalone>
+ Primary
+ </XDSLink>
+ <XDSLink onClick={() => {}} color="secondary" isStandalone>
+ Secondary
+ </XDSLink>
+ <XDSLink onClick={() => {}} color="inherit" isStandalone>
+ Inherit
+ </XDSLink>
+ </div>
+ <div style={{display: 'flex', gap: '16px', alignItems: 'center'}}>
+ <XDSLink onClick={() => {}} hasUnderline isStandalone>
+ With underline
+ </XDSLink>
+ <XDSLink onClick={() => {}} tooltip="Action tooltip" isStandalone>
+ With tooltip
+ </XDSLink>
+ <XDSLink onClick={() => {}} isDisabled isStandalone>
+ Disabled
+ </XDSLink>
+ </div>
+ </div>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'Button fallback supports all visual variants (color, underline, tooltip, disabled) — ' +
+ 'visually indistinguishable from a regular link.',
+ },
+ },
+ },
+};
+
+export const ButtonFallbackInline: Story = {
+ render: () => (
+ <XDSText type="body">
+ You can <XDSLink onClick={() => alert('Undo!')}>undo this action</XDSLink>{' '}
+ if you change your mind.
+ </XDSText>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'Button fallback works inline within text, just like a regular link. ' +
+ 'Inspect the DOM — it renders a `<button>` not an `<a>`.',
+ },
+ },
+ },
+};
+
+export const LinkVsButtonComparison: Story = {
+ render: () => (
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '16px',
+ maxWidth: '600px',
+ }}>
+ <XDSText type="large" size="sm">
+ Link (with href) vs Button (without href)
+ </XDSText>
+ <div style={{display: 'flex', gap: '24px', alignItems: 'center'}}>
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '4px',
+ alignItems: 'center',
+ }}>
+ <XDSLink href="/destination" isStandalone>
+ I navigate
+ </XDSLink>
+ <XDSText type="body" size="sm" color="secondary">
+ {'<a href="/destination">'}
+ </XDSText>
+ </div>
+ <div
+ style={{
+ display: 'flex',
+ flexDirection: 'column',
+ gap: '4px',
+ alignItems: 'center',
+ }}>
+ <XDSLink onClick={() => alert('Action!')} isStandalone>
+ I act
+ </XDSLink>
+ <XDSText type="body" size="sm" color="secondary">
+ {'<button type="button">'}
+ </XDSText>
+ </div>
+ </div>
+ <XDSText type="body" size="sm" color="secondary">
+ Both look the same — but inspect the DOM to see the semantic difference.
+ </XDSText>
+ </div>
+ ),
+ parameters: {
+ docs: {
+ description: {
+ story:
+ 'Side-by-side comparison showing that links and button fallbacks are visually identical. ' +
+ 'The only difference is in the rendered DOM element.',
+ },
+ },
+ },
+};
diff --git a/packages/core/src/Link/XDSLink.test.tsx b/packages/core/src/Link/XDSLink.test.tsx
index 312c28c9d5..049db2c849 100644
--- a/packages/core/src/Link/XDSLink.test.tsx
+++ b/packages/core/src/Link/XDSLink.test.tsx
@@ -38,6 +38,48 @@ describe('XDSLink', () => {
expect(screen.getByRole('link')).toHaveAttribute('href', '/destination');
});
+ it('renders as a button when href is undefined', () => {
+ render(<XDSLink>Action</XDSLink>);
+ expect(screen.getByRole('button', {name: 'Action'})).toBeInTheDocument();
+ });
+
+ it('renders as a button when href is explicitly undefined', () => {
+ render(<XDSLink href={undefined}>Action</XDSLink>);
+ expect(screen.getByRole('button', {name: 'Action'})).toBeInTheDocument();
+ });
+
+ it('button fallback fires onClick', async () => {
+ const user = userEvent.setup();
+ const handleClick = vi.fn();
+ render(<XDSLink onClick={handleClick}>Click me</XDSLink>);
+
+ await user.click(screen.getByRole('button'));
+ expect(handleClick).toHaveBeenCalledTimes(1);
+ });
+
+ it('button fallback supports isDisabled', () => {
+ render(<XDSLink isDisabled>Disabled Action</XDSLink>);
+ const button = screen.getByRole('button');
+ expect(button).toBeDisabled();
+ });
+
+ it('button fallback has type="button"', () => {
+ render(<XDSLink>Action</XDSLink>);
+ expect(screen.getByRole('button')).toHaveAttribute('type', 'button');
+ });
+
+ it('button fallback supports aria-label via label prop', () => {
+ render(
+ <XDSLink label="Close dialog">
+ <span aria-hidden="true">✕</span>
+ </XDSLink>,
+ );
+ expect(screen.getByRole('button')).toHaveAttribute(
+ 'aria-label',
+ 'Close dialog',
+ );
+ });
+
it('does not render aria-label when label is omitted', () => {
render(<XDSLink href="/test">Visible text</XDSLink>);
expect(screen.getByRole('link')).not.toHaveAttribute('aria-label');
diff --git a/packages/core/src/Link/XDSLink.tsx b/packages/core/src/Link/XDSLink.tsx
index cd626f4693..d5c6d7ad23 100644
--- a/packages/core/src/Link/XDSLink.tsx
+++ b/packages/core/src/Link/XDSLink.tsx
@@ -73,6 +73,17 @@ const styles = stylex.create({
':focus-visible': '2px',
},
},
+ /**
+ * Reset styles for rendering as a <button> when href is undefined.
+ * Strips all native button chrome so it looks identical to a link.
+ */
+ buttonReset: {
+ backgroundColor: 'transparent',
+ borderStyle: 'none',
+ padding: 0,
+ pointerEvents: 'auto',
+ position: 'relative',
+ },
hasUnderline: {
textDecoration: 'underline',
},
@@ -112,13 +123,16 @@ const linkColorStyles = stylex.create({
},
});
-export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {
+export interface XDSLinkProps extends XDSBaseProps<
+ HTMLAnchorElement | HTMLButtonElement
+> {
/** Ref forwarded to the root element */
- ref?: React.Ref<HTMLAnchorElement>;
+ ref?: React.Ref<HTMLAnchorElement | HTMLButtonElement>;
/**
* Custom component to render instead of `<a>`.
* Overrides the provider-level default set by XDSLinkProvider.
* Must accept href, className, style, and children props.
+ * Only used when href is provided.
*/
as?: XDSLinkComponentType;
/**
@@ -130,6 +144,8 @@ export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {
label?: string;
/**
* Link destination URL.
+ * When undefined, renders as a `<button>` with link styling
+ * for semantic correctness and accessibility.
*/
href?: string;
/**
@@ -169,9 +185,10 @@ export interface XDSLinkProps extends XDSBaseProps<HTMLAnchorElement> {
*/
referrerPolicy?: React.HTMLAttributeReferrerPolicy;
/**
- * Click handler. Fires before navigation.
+ * Click handler. Fires before navigation (when href is set),
+ * or as the primary action (when href is undefined).
*/
- onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+ onClick?: React.MouseEventHandler<HTMLAnchorElement | HTMLButtonElement>;
/**
* Tooltip text to display on hover.
*/
@@ -263,30 +280,11 @@ export function XDSLink({
relFromProps,
);
- const linkElement = (
- <LinkComponent
- ref={ref}
- href={href}
- target={target}
- rel={rel}
- onClick={onClick}
- aria-label={label || undefined}
- aria-disabled={isDisabled || undefined}
- tabIndex={isDisabled ? -1 : undefined}
- {...mergeProps(
- xdsClassName('link', {color}),
- stylex.props(
- styles.base,
- linkColorStyles[color],
- hasUnderline && styles.hasUnderline,
- isStandalone && styles.standalone,
- isDisabled && styles.disabled,
- xstyle,
- ),
- className,
- style,
- )}
- {...props}>
+ // When href is undefined, render as a <button> for semantic correctness
+ const renderAsButton = href == null;
+
+ const sharedContent = (
+ <>
<XDSText
type={type}
size={size}
@@ -296,12 +294,76 @@ export function XDSLink({
maxLines={maxLines}>
{children}
</XDSText>
- {isExternalLink && (
+ {isExternalLink && !renderAsButton && (
<XDSIcon icon="externalLink" size="xsm" color="inherit" />
)}
- </LinkComponent>
+ </>
);
+ let linkElement: React.ReactElement;
+
+ if (renderAsButton) {
+ linkElement = (
+ <button
+ ref={ref as React.Ref<HTMLButtonElement>}
+ type="button"
+ onClick={
+ onClick
+ }
+ aria-label={label || undefined}
+ aria-disabled={isDisabled || undefined}
+ tabIndex={isDisabled ? -1 : undefined}
+ disabled={isDisabled}
+ {...mergeProps(
+ xdsClassName('link', {color}),
+ stylex.props(
+ styles.base,
+ styles.buttonReset,
+ linkColorStyles[color],
+ hasUnderline && styles.hasUnderline,
+ isStandalone && styles.standalone,
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ className,
+ style,
+ )}
+ {...(props)}>
+ {sharedContent}
+ </button>
+ );
+ } else {
+ linkElement = (
+ <LinkComponent
+ ref={ref as React.Ref<HTMLAnchorElement>}
+ href={href}
+ target={target}
+ rel={rel}
+ onClick={
+ onClick
+ }
+ aria-label={label || undefined}
+ aria-disabled={isDisabled || undefined}
+ tabIndex={isDisabled ? -1 : undefined}
+ {...mergeProps(
+ xdsClassName('link', {color}),
+ stylex.props(
+ styles.base,
+ linkColorStyles[color],
+ hasUnderline && styles.hasUnderline,
+ isStandalone && styles.standalone,
+ isDisabled && styles.disabled,
+ xstyle,
+ ),
+ className,
+ style,
+ )}
+ {...props}>
+ {sharedContent}
+ </LinkComponent>
+ );
+ }
+
// Wrap with tooltip if provided
if (tooltip) {
return (