feat(ActionList): Combine Item and LinkItem into unified Item component #6999

liuliu-dev · 2025-10-13T22:27:17Z

Summary

Unifies ActionList.Item and ActionList.LinkItem into a single ActionList.Item component that handles both regular items and link items. Users can create link items by simply adding href or other anchor attributes to ActionList.Item, without needing to choose between two separate components.

All existing ActionList.LinkItem usage continues to work unchanged.

Closes https://github.com/github/primer/issues/5956

Implementation

Link Container
Created LinkItemContainerNoBox following the pattern of ButtonItemContainerNoBox /DivItemContainerNoBox, used as ItemWrapper when Item should be rendered as a link .

The structure is similar to _PrivateItemWrapper used in the LinkItem, but with some props changes : passing userOnClick and inactiveText which are no longer in scope.

Props Merging
The challenge is ActionListItemProps now includes both previous ActionListItemProps and LinkProps.

To avoid breaking current usage and support migration from ActionList.LinkItem to ActionList.Item with just the component name change (no props change), defined INTERACTIVE_ELEMENT_PROPS const in shared.ts. This const is used to strip LinkItem-specific props and only pass containerOnlyProps to container, avoiding props like href showing up in <li>.

Props are split into interactiveProps and containerOnlyProps.

Migration
Change component name, props stay the same:

// Before
<ActionList.LinkItem href="/path">Link</ActionList.LinkItem>

// After
<ActionList.Item href="/path">Link</ActionList.Item>

Breaking Changes

ActionList.LinkItem deprecated (still works but will show deprecation warnings)
ActionListItemProps now includes link props. And removed unused type prop from LinkProps, it caused type conflicts(https://github.com/github/github-ui/blob/b6bf6d94ab0a339243ebdcad5e6eeefce2b93f48/packages/copilot-chat/components/autocomplete/FileSuggestion.tsx#L8) when extending the interface.

Notes

The ESLint rule primer-react/prefer-action-list-item-onselect will need to be updated to allow onClick when link props are present.
Are these conditions sufficient to detect link items? Should any other props trigger link behavior?

  const isLinkItem = Boolean(
    props.href ||
      props.download ||
      props.target ||
      props.rel ||
      props.hrefLang ||
      props.to ||
      (typeof props.as === 'string' && props.as.toLowerCase() === 'a') ||
      role === 'link',
  )

Rollout strategy

Major release; if selected, include a written rollout or migration plan

…ories and checked DOM rendering

…structure.

…-and-item-in-actionlist

changeset-bot · 2025-10-13T22:27:21Z

🦋 Changeset detected

Latest commit: 54ee453

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

This PR includes changesets to release 2 packages

Name	Type
@primer/react	Major
@primer/styled-react	Major

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

github-actions · 2025-10-13T22:27:52Z

👋 Hi, this pull request contains changes to the source code that github/github depends on. If you are GitHub staff, we recommend testing these changes with github/github using the integration workflow. Thanks!

…//github.com/primer/react into liuliu/merge-linkitem-and-item-in-actionlist

…-and-item-in-actionlist

Copilot

Pull Request Overview

This PR unifies ActionList.Item and ActionList.LinkItem into a single component by enabling ActionList.Item to handle both regular items and link items based on the presence of link-related props (e.g., href, target, to). Users can now create link items by simply adding anchor attributes to ActionList.Item, eliminating the need to choose between two separate components. The existing ActionList.LinkItem remains functional but is now deprecated.

Key changes include:

Creation of LinkItemContainerNoBox component to handle link rendering within items
Extension of ActionListItemProps to include LinkProps for link-related attributes
Introduction of INTERACTIVE_ELEMENT_PROPS constant to properly distribute props between container and interactive elements
Deprecation of ActionList.LinkItem with backward compatibility maintained

Reviewed Changes

Copilot reviewed 20 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/react/src/ActionList/shared.ts	Adds `LinkProps` type and `INTERACTIVE_ELEMENT_PROPS` constant for props distribution; extends `ActionListItemProps` to include link props
packages/react/src/ActionList/Item.tsx	Implements unified item logic with link detection, adds `LinkItemContainerNoBox` component, and splits props between container and interactive elements
packages/react/src/ActionList/LinkItem.tsx	Refactors to import `LinkProps` from shared.ts and removes duplicate type definition
packages/react/src/ActionList/index.ts	Updates `LinkItem` export with deprecation notice
packages/react/src/ActionList/ActionList.docs.json	Adds documentation for new link-related props on `ActionList.Item`
Multiple story and test files	Migrates `ActionList.LinkItem` usage to `ActionList.Item` with `href` prop throughout examples, tests, and stories
packages/react/src/NavList/NavList.tsx	Updates NavList to use `ActionList.Item` with `as="a"` instead of `ActionList.LinkItem`
packages/react/src/UnderlineNav/UnderlineNav.tsx	Migrates from `ActionList.LinkItem` to `ActionList.Item` with ESLint disable comment for `onClick`
.changeset/shiny-pianos-wash.md	Adds changeset documenting the major breaking change

packages/react/src/PageLayout/PageLayout.examples.stories.tsx

Copilot · 2025-10-16T00:47:10Z

packages/react/src/ActionList/Item.tsx

+          ...props,
+          ...menuItemProps,
+          inactiveText,
+          userOnClick: interactiveProps.onClick as ((event: React.MouseEvent<HTMLAnchorElement>) => void) | undefined,


The type assertion could be replaced with a safer type guard or validation. Consider checking if interactiveProps.onClick is a function before passing it as userOnClick to avoid potential runtime issues if the value is not actually a function.

Suggested change

userOnClick: interactiveProps.onClick as ((event: React.MouseEvent<HTMLAnchorElement>) => void) | undefined,

userOnClick: typeof interactiveProps.onClick === 'function' ? interactiveProps.onClick : undefined,

packages/react/src/ActionList/shared.ts

Copilot · 2025-10-16T00:47:11Z

packages/react/src/ActionList/Item.tsx

+  const isLinkItem = Boolean(
+    props.href ||
+      props.download ||
+      props.target ||
+      props.rel ||
+      props.hrefLang ||
+      props.to ||
+      (typeof props.as === 'string' && props.as.toLowerCase() === 'a') ||
+      role === 'link',
+  )


[nitpick] The link detection logic could be extracted into a utility function (e.g., isLinkItemProps) to improve testability and reusability. This would make it easier to maintain the logic if the criteria for detecting link items changes in the future.

siddharthkp · 2025-10-16T10:32:42Z

.changeset/shiny-pianos-wash.md

+'@primer/react': major
+---
+
+ActionList.Item now supports link functionality through href and other anchor attributes, deprecating the separate ActionList.LinkItem component.


Hi!

What does the deprecation show up as? Does it show up as an error in CI for github-ui or only a soft suggestion in vscode?

It would only be a suggestion in vscode like this:

github-actions · 2025-10-17T20:01:46Z

👋 Hi, there are new commits since the last successful integration test. We recommend running the integration workflow once more, unless you are sure the new changes do not affect github/github. Thanks!

github-actions · 2025-10-20T23:28:42Z

👋 Hi, there are new commits since the last successful integration test. We recommend running the integration workflow once more, unless you are sure the new changes do not affect github/github. Thanks!

primer-integration · 2025-10-20T23:46:21Z

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/5128

siddharthkp

Big PR with tricky changes, well done!

Left some questions to understand the changes better

siddharthkp · 2025-10-21T12:48:59Z

packages/react/src/NavList/NavList.tsx

-      <ActionList.LinkItem
+      <ActionList.Item
        ref={ref}
+        as="a"


This has as="a" but does not have an href or to, should we throw a typescript error when that happens?

I think it makes sense to validate for href or to when as="a" is used

I added validation in Item.tsx:

if (typeof props.as === 'string' && props.as.toLowerCase() === 'a' && !inactiveText) { invariant( props.href || props.to, 'ActionList.Item with as="a" must have an href or to prop for proper link semantics and accessibility.', ) }

However, this will break existing usages in github-ui where NavList.Item is used without href (like this example).

siddharthkp · 2025-10-21T13:24:01Z

packages/react/src/UnderlineNav/UnderlineNav.tsx

+                      <ActionList.Item
                        key={menuItemChildren}
                        style={menuItemStyles}
+                        /* eslint-disable-next-line primer-react/prefer-action-list-item-onselect */


(non blocker) worth asking @pksjce or @broccolinisoup if there is a reason to prefer onClick over onSelect or if we can use onSelect here

siddharthkp · 2025-10-21T13:25:59Z

packages/react/src/ActionList/ActionList.dev.stories.tsx

            Item with inline description
            <ActionList.Description variant="block">Block description</ActionList.Description>
-          </ActionList.LinkItem>
+          </ActionList.Item>


I think we should keep one story for LinkItem in ActionList.dev.stories so that we don't accidentally break it before it's time to remove ActionList.LinkItem.

siddharthkp · 2025-10-21T13:30:15Z

packages/react/src/ActionList/Item.tsx

+      props.hrefLang ||
+      props.to ||
+      (typeof props.as === 'string' && props.as.toLowerCase() === 'a') ||
+      role === 'link',


can we reduce this list to the main things that make it anchor tag

For example, having hrefLang without href does not make it a link. I imagine the list is just href, as and to.

siddharthkp · 2025-10-21T13:35:05Z

packages/react/src/ActionList/shared.ts

+ * - Test identifiers
+ */
+export const INTERACTIVE_ELEMENT_PROPS = [
+  // Link-specific props from LinkProps


How can we make sure this list is exhaustive?

siddharthkp · 2025-10-21T13:35:28Z

packages/react/src/ActionList/shared.ts

+  'aria-keyshortcuts',
+  // Styling props (should be on the interactive element)
+  'style',
+  'sx',


just checking, do we still want sx here?

siddharthkp · 2025-10-21T13:41:37Z

packages/react/src/ActionList/Item.tsx

+  const interactiveProps: Record<string, unknown> = {}
+
+  for (const [key, value] of Object.entries(props)) {
+    if (interactivePropsSet.has(key)) {


Sorry, just curious, is there a benefit of converting the array into a set to use Set.has instead of Array.includes? Took me a second to follow the trail 😅

siddharthkp · 2025-10-21T13:45:25Z

packages/react/src/ActionList/Item.tsx

+  // 3. default - regular button/div behavior
+
+  // Create a Set for lookup of interactive-only props
+  const interactivePropsSet = new Set<string>(INTERACTIVE_ELEMENT_PROPS)


This is a longer list than what we checked before, are there any props that were earlier going to the <li> that will now end up on <a>? Especially in instances where ActionList.Item was used to act like a Link

For example: ActionList.Item as="a" href="" or ActionList.Item onClick={...}

siddharthkp · 2025-10-21T13:49:01Z

packages/react/src/ActionList/Item.tsx

-      }
+    : isLinkItem
+      ? {
+          ...props,


just checking, do we want to spread all the props here? Or only some of the props?

siddharthkp · 2025-10-21T13:49:12Z

packages/react/src/ActionList/Item.tsx

+          ...props,
+          ...menuItemProps,
+          inactiveText,
+          userOnClick: interactiveProps.onClick as ((event: React.MouseEvent<HTMLAnchorElement>) => void) | undefined,


Are we also using the other props in interactiveProps somewhere else? I could only spot onClick?

siddharthkp · 2025-10-21T13:54:14Z

ci completed with status success.

Heads up! There seem to be more tests that are failing in the integration PR that the comment does not know about: https://github.com/github/github-ui/pull/5128. I have not checked if they are related to changes in this PR, may or may not be.

…-and-item-in-actionlist

…tem story

github-actions · 2025-10-21T18:53:51Z

👋 Hi, there are new commits since the last successful integration test. We recommend running the integration workflow once more, unless you are sure the new changes do not affect github/github. Thanks!

primer-integration · 2025-10-21T21:18:49Z

🔴 ci completed with status failure.

liuliu-dev added 5 commits October 10, 2025 15:06

draft: LinkItemContainerNoBox, replaced all LinkItem in ActionList st…

1e2f576

…ories and checked DOM rendering

add back _PrivateItemWrapper, change api in stories and test the dom …

d779acf

…structure.

fix tests for missing role

1f686e8

Merge remote-tracking branch 'origin/main' into liuliu/merge-linkitem…

1704d0d

…-and-item-in-actionlist

fix lint

e1a6a6b

github-actions bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Oct 13, 2025

liuliu-dev deployed to github-pages October 13, 2025 22:35 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 13, 2025 22:35 Inactive

liuliu-dev added the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Oct 13, 2025

test(vrt): update snapshots

35dc470

github-actions bot removed the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Oct 13, 2025

primer bot deployed to github-pages October 13, 2025 23:06 View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 13, 2025 23:06 Inactive

liuliu-dev added 2 commits October 14, 2025 13:42

update Breadcrumbs, NavList, UnderlineNav to use ActionList.Item

24995ef

Merge branch 'liuliu/merge-linkitem-and-item-in-actionlist' of https:…

02f7861

…//github.com/primer/react into liuliu/merge-linkitem-and-item-in-actionlist

liuliu-dev deployed to github-pages October 14, 2025 20:52 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 14, 2025 20:53 Inactive

liuliu-dev added 2 commits October 14, 2025 15:56

some clean up and add changeset

1c904ac

Merge remote-tracking branch 'origin/main' into liuliu/merge-linkitem…

ebb427f

…-and-item-in-actionlist

liuliu-dev added the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Oct 14, 2025

github-actions bot requested a deployment to storybook-preview-6999 October 14, 2025 23:00 Abandoned

test(vrt): update snapshots

9883e75

github-actions bot removed the update snapshots 🤖 Command that updates VRT snapshots on the pull request label Oct 14, 2025

github-actions bot temporarily deployed to storybook-preview-6999 October 14, 2025 23:08 Inactive

primer bot deployed to github-pages October 14, 2025 23:16 View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 14, 2025 23:16 Inactive

github-actions bot added integration-tests: failing Changes in this PR cause breaking changes in gh/gh and removed integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels Oct 14, 2025

Copilot AI reviewed Oct 16, 2025

View reviewed changes

siddharthkp reviewed Oct 16, 2025

View reviewed changes

resolve conflicts

33b46fe

github-actions bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Oct 17, 2025

liuliu-dev deployed to github-pages October 17, 2025 20:10 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 17, 2025 20:10 Inactive

h4 -> h2, not exporting MenuItemProps

61eb1f1

github-actions bot added integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm and removed integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels Oct 20, 2025

liuliu-dev deployed to github-pages October 20, 2025 23:37 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 20, 2025 23:38 Inactive

github-actions bot removed the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Oct 20, 2025

siddharthkp requested changes Oct 21, 2025

View reviewed changes

liuliu-dev added 2 commits October 21, 2025 11:49

Merge remote-tracking branch 'origin/main' into liuliu/merge-linkitem…

2a1be72

…-and-item-in-actionlist

check for href and to on as a, clean up props logic, add back 1 linki…

d1f1272

…tem story

github-actions bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Oct 21, 2025

liuliu-dev deployed to github-pages October 21, 2025 19:02 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-6999 October 21, 2025 19:03 Inactive

remove href check for a

54ee453

liuliu-dev deployed to github-pages October 21, 2025 22:51 — with GitHub Actions View deployment

github-actions bot deployed to storybook-preview-6999 October 21, 2025 22:52 View deployment

	userOnClick: interactiveProps.onClick as ((event: React.MouseEvent<HTMLAnchorElement>) => void) \| undefined,
	userOnClick: typeof interactiveProps.onClick === 'function' ? interactiveProps.onClick : undefined,

feat(ActionList): Combine Item and LinkItem into unified Item component #6999

Are you sure you want to change the base?

feat(ActionList): Combine Item and LinkItem into unified Item component #6999

Uh oh!

Conversation

liuliu-dev commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Implementation

Breaking Changes

Notes

Rollout strategy

Uh oh!

changeset-bot bot commented Oct 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Oct 13, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Oct 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Oct 16, 2025

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!

github-actions bot commented Oct 17, 2025

Uh oh!

github-actions bot commented Oct 20, 2025

Uh oh!

primer-integration bot commented Oct 20, 2025

Uh oh!

siddharthkp left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

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!

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!

siddharthkp commented Oct 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Oct 21, 2025

Uh oh!

primer-integration bot commented Oct 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

liuliu-dev commented Oct 13, 2025 •

edited

Loading

changeset-bot bot commented Oct 13, 2025 •

edited

Loading

siddharthkp left a comment •

edited

Loading

siddharthkp commented Oct 21, 2025 •

edited

Loading