fix(link): link overriding role

[hasegawa-101]

Closes #5993

📝 Description

Fixed an issue where the role attribute on the Link component could not be overridden by the user (e.g., role="button"). This PR updates the mergeProps order to prioritize user-defined props while strictly preserving the correctly resolved href from react-aria to maintain router compatibility.

⛳️ Current behavior (updates)

The Link component strictly prioritizes system default props over user-provided props. As a result, passing role="button" is ignored, and the component always renders with role="link", preventing users from creating button-like links purely via props.

🚀 New behavior

• User Priority: Updated mergeProps order to prioritize otherProps (user input).
• Href Safety: Explicitly restores the system-resolved href from linkProps to prevent it from being overwritten by raw props, ensuring correct routing paths (e.g., handling basePath).

💣 Is this a breaking change (Yes/No):

No

📝 Additional Information

[vercel]

@hasegawa-101 is attempting to deploy a commit to the HeroUI Inc Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 878a6be

The changes in this PR will be included in the next version bump.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[coderabbitai]

Walkthrough

This PR fixes a bug where the Link component incorrectly overrode the role attribute when rendered as a button. Changes include a changeset entry, a new test case verifying button rendering with role preservation, and a modification to the use-link hook to correct prop merging order.

Changes

Cohort / File(s)	Summary
Changeset entry .changeset/real-turkeys-roll.md	Documents patch release for @heroui/link addressing role attribute override issue
Test coverage packages/components/link/__tests__/link.test.tsx	Adds test case validating Link component renders as button with correct role, type, and without href attribute when as="button"
Link hook logic packages/components/link/src/use-link.ts	Adjusts prop merging order in getLinkProps return to ensure href from linkProps is preserved and not overridden by spread props

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

• Attention area: The prop merging order change in use-link.ts — verify the new merge sequence correctly prioritizes href while allowing custom role attributes to pass through without being overridden.

Possibly related PRs

• fix(link): resolve issue where useHref is not working correctly #5933: Also modifies packages/components/link/src/use-link.ts to fix prop-merge order and preserve href precedence; this PR addresses a regression introduced by that change.

Suggested reviewers

• jrgarciadev
• wingkwong

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main fix: resolving the Link component's issue with overriding the role property.
Linked Issues check	✅ Passed	The code changes directly address the bug in issue #5993: preserving the role prop when the Link is rendered as another element (e.g., as="button").
Out of Scope Changes check	✅ Passed	All changes (test, use-link.ts, changeset) are focused on fixing the role prop override issue; no unrelated modifications detected.
Description check	✅ Passed	The PR description includes all required sections from the template with substantive content addressing the issue, current behavior, new behavior, and breaking change status.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

@heroui/accordion

npm i https://pkg.pr.new/@heroui/accordion@5999

@heroui/alert

npm i https://pkg.pr.new/@heroui/alert@5999

@heroui/autocomplete

npm i https://pkg.pr.new/@heroui/autocomplete@5999

@heroui/avatar

npm i https://pkg.pr.new/@heroui/avatar@5999

@heroui/badge

npm i https://pkg.pr.new/@heroui/badge@5999

@heroui/breadcrumbs

npm i https://pkg.pr.new/@heroui/breadcrumbs@5999

@heroui/button

npm i https://pkg.pr.new/@heroui/button@5999

@heroui/calendar

npm i https://pkg.pr.new/@heroui/calendar@5999

@heroui/card

npm i https://pkg.pr.new/@heroui/card@5999

@heroui/checkbox

npm i https://pkg.pr.new/@heroui/checkbox@5999

@heroui/chip

npm i https://pkg.pr.new/@heroui/chip@5999

@heroui/code

npm i https://pkg.pr.new/@heroui/code@5999

@heroui/date-input

npm i https://pkg.pr.new/@heroui/date-input@5999

@heroui/date-picker

npm i https://pkg.pr.new/@heroui/date-picker@5999

@heroui/divider

npm i https://pkg.pr.new/@heroui/divider@5999

@heroui/drawer

npm i https://pkg.pr.new/@heroui/drawer@5999

@heroui/dropdown

npm i https://pkg.pr.new/@heroui/dropdown@5999

@heroui/form

npm i https://pkg.pr.new/@heroui/form@5999

@heroui/image

npm i https://pkg.pr.new/@heroui/image@5999

@heroui/input

npm i https://pkg.pr.new/@heroui/input@5999

@heroui/input-otp

npm i https://pkg.pr.new/@heroui/input-otp@5999

@heroui/kbd

npm i https://pkg.pr.new/@heroui/kbd@5999

@heroui/link

npm i https://pkg.pr.new/@heroui/link@5999

@heroui/listbox

npm i https://pkg.pr.new/@heroui/listbox@5999

@heroui/menu

npm i https://pkg.pr.new/@heroui/menu@5999

@heroui/modal

npm i https://pkg.pr.new/@heroui/modal@5999

@heroui/navbar

npm i https://pkg.pr.new/@heroui/navbar@5999

@heroui/number-input

npm i https://pkg.pr.new/@heroui/number-input@5999

@heroui/pagination

npm i https://pkg.pr.new/@heroui/pagination@5999

@heroui/popover

npm i https://pkg.pr.new/@heroui/popover@5999

@heroui/progress

npm i https://pkg.pr.new/@heroui/progress@5999

@heroui/radio

npm i https://pkg.pr.new/@heroui/radio@5999

@heroui/ripple

npm i https://pkg.pr.new/@heroui/ripple@5999

@heroui/scroll-shadow

npm i https://pkg.pr.new/@heroui/scroll-shadow@5999

@heroui/select

npm i https://pkg.pr.new/@heroui/select@5999

@heroui/skeleton

npm i https://pkg.pr.new/@heroui/skeleton@5999

@heroui/slider

npm i https://pkg.pr.new/@heroui/slider@5999

@heroui/snippet

npm i https://pkg.pr.new/@heroui/snippet@5999

@heroui/spacer

npm i https://pkg.pr.new/@heroui/spacer@5999

@heroui/spinner

npm i https://pkg.pr.new/@heroui/spinner@5999

@heroui/switch

npm i https://pkg.pr.new/@heroui/switch@5999

@heroui/table

npm i https://pkg.pr.new/@heroui/table@5999

@heroui/tabs

npm i https://pkg.pr.new/@heroui/tabs@5999

@heroui/toast

npm i https://pkg.pr.new/@heroui/toast@5999

@heroui/tooltip

npm i https://pkg.pr.new/@heroui/tooltip@5999

@heroui/user

npm i https://pkg.pr.new/@heroui/user@5999

@heroui/react

npm i https://pkg.pr.new/@heroui/react@5999

@heroui/system

npm i https://pkg.pr.new/@heroui/system@5999

@heroui/system-rsc

npm i https://pkg.pr.new/@heroui/system-rsc@5999

@heroui/theme

npm i https://pkg.pr.new/@heroui/theme@5999

@heroui/use-aria-accordion

npm i https://pkg.pr.new/@heroui/use-aria-accordion@5999

@heroui/use-aria-accordion-item

npm i https://pkg.pr.new/@heroui/use-aria-accordion-item@5999

@heroui/use-aria-button

npm i https://pkg.pr.new/@heroui/use-aria-button@5999

@heroui/use-aria-link

npm i https://pkg.pr.new/@heroui/use-aria-link@5999

@heroui/use-aria-modal-overlay

npm i https://pkg.pr.new/@heroui/use-aria-modal-overlay@5999

@heroui/use-aria-multiselect

npm i https://pkg.pr.new/@heroui/use-aria-multiselect@5999

@heroui/use-aria-overlay

npm i https://pkg.pr.new/@heroui/use-aria-overlay@5999

@heroui/use-callback-ref

npm i https://pkg.pr.new/@heroui/use-callback-ref@5999

@heroui/use-clipboard

npm i https://pkg.pr.new/@heroui/use-clipboard@5999

@heroui/use-data-scroll-overflow

npm i https://pkg.pr.new/@heroui/use-data-scroll-overflow@5999

@heroui/use-disclosure

npm i https://pkg.pr.new/@heroui/use-disclosure@5999

@heroui/use-draggable

npm i https://pkg.pr.new/@heroui/use-draggable@5999

@heroui/use-form-reset

npm i https://pkg.pr.new/@heroui/use-form-reset@5999

@heroui/use-image

npm i https://pkg.pr.new/@heroui/use-image@5999

@heroui/use-infinite-scroll

npm i https://pkg.pr.new/@heroui/use-infinite-scroll@5999

@heroui/use-intersection-observer

npm i https://pkg.pr.new/@heroui/use-intersection-observer@5999

@heroui/use-is-mobile

npm i https://pkg.pr.new/@heroui/use-is-mobile@5999

@heroui/use-is-mounted

npm i https://pkg.pr.new/@heroui/use-is-mounted@5999

@heroui/use-measure

npm i https://pkg.pr.new/@heroui/use-measure@5999

@heroui/use-pagination

npm i https://pkg.pr.new/@heroui/use-pagination@5999

@heroui/use-real-shape

npm i https://pkg.pr.new/@heroui/use-real-shape@5999

@heroui/use-ref-state

npm i https://pkg.pr.new/@heroui/use-ref-state@5999

@heroui/use-resize

npm i https://pkg.pr.new/@heroui/use-resize@5999

@heroui/use-safe-layout-effect

npm i https://pkg.pr.new/@heroui/use-safe-layout-effect@5999

@heroui/use-scroll-position

npm i https://pkg.pr.new/@heroui/use-scroll-position@5999

@heroui/use-ssr

npm i https://pkg.pr.new/@heroui/use-ssr@5999

@heroui/use-theme

npm i https://pkg.pr.new/@heroui/use-theme@5999

@heroui/use-update-effect

npm i https://pkg.pr.new/@heroui/use-update-effect@5999

@heroui/use-viewport-size

npm i https://pkg.pr.new/@heroui/use-viewport-size@5999

@heroui/aria-utils

npm i https://pkg.pr.new/@heroui/aria-utils@5999

@heroui/dom-animation

npm i https://pkg.pr.new/@heroui/dom-animation@5999

@heroui/framer-utils

npm i https://pkg.pr.new/@heroui/framer-utils@5999

@heroui/react-rsc-utils

npm i https://pkg.pr.new/@heroui/react-rsc-utils@5999

@heroui/react-utils

npm i https://pkg.pr.new/@heroui/react-utils@5999

@heroui/shared-icons

npm i https://pkg.pr.new/@heroui/shared-icons@5999

@heroui/shared-utils

npm i https://pkg.pr.new/@heroui/shared-utils@5999

@heroui/stories-utils

npm i https://pkg.pr.new/@heroui/stories-utils@5999

@heroui/test-utils

npm i https://pkg.pr.new/@heroui/test-utils@5999

commit: 878a6be

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/components/link/__tests__/link.test.tsx (1)

102-114: Test validates the fix but could be more explicit.

The test correctly verifies that as="button" with explicit role="button" renders as a button element. Using getByRole("button") implicitly validates that role="button" is present, which is good.

However, consider these improvements:

1. Explicit role assertion: Add expect(button).toHaveAttribute("role", "button") to make the role validation explicit rather than implicit.

2. Regression test: Add a test case for the exact scenario from issue #5993: as="button" href="#" role="button" to ensure the explicit role is preserved even when href is present.

Example addition:

+  it("should respect explicit role even when href is present", () => {
+    const {getByRole} = render(
+      <Link as="button" href="#" role="button" type="button">
+        Button Link
+      </Link>,
+    );
+
+    const button = getByRole("button");
+
+    expect(button.tagName).toBe("BUTTON");
+    expect(button).toHaveAttribute("role", "button");
+    expect(button).toHaveAttribute("type", "button");
+  });

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between acc74d1 and 878a6be.

📒 Files selected for processing (3)

• .changeset/real-turkeys-roll.md (1 hunks)
• packages/components/link/__tests__/link.test.tsx (1 hunks)
• packages/components/link/src/use-link.ts (2 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (3)

• GitHub Check: TypeScript
• GitHub Check: Continuous Release
• GitHub Check: Build

🔇 Additional comments (3)

packages/components/link/src/use-link.ts (2)

3-3: LGTM: Import addition supports type cast.

The AnchorHTMLAttributes import is necessary for the type cast on line 114.

---

113-115: Verify the prop merging order and type cast.

The reordering of mergeProps arguments (placing otherProps after linkProps) correctly allows user-provided props to override computed props. Analysis confirms:

1. mergeProps behavior verified: For all other props, the last prop object overrides all previous ones. The explicit href override placement as the last argument ensures it always comes from linkProps.

2. href handling on non-anchor elements is safe: The code passes elementType: \${as}`touseAriaLink(line 82). React Aria'suseLinkreturns element-type-aware props—for button elements, it doesn't includehrefinlinkProps. Therefore, (linkProps as AnchorHTMLAttributes).hrefisundefined` for buttons, preventing invalid href attributes from being added.

3. Type cast concern noted: The cast indicates a potential typing mismatch with useAriaLink's return type, but this doesn't cause runtime issues. The test suite validates that button elements correctly exclude href attributes.

.changeset/real-turkeys-roll.md (1)

1-5: LGTM: Changeset correctly documents the fix.

The changeset properly documents this as a patch release for @heroui/link with a clear reference to issue #5993.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
heroui	Ready	Preview, Comment	Dec 17, 2025 1:54pm
heroui-sb	Ready	Preview, Comment	Dec 17, 2025 1:54pm