BranchName: Add `leadingVisual`, `trailingAction` and `description` by siddharthkp · Pull Request #7993 · primer/react

siddharthkp · 2026-06-15T14:29:20Z

Closes https://github.com/github/primer/issues/6684
API working notes: https://gist.github.com/siddharthkp/4895ceac16b0b64d219594c08f7897a4
Merged after https://github.com/github/github-ui/pull/23799

API proposal document for upstreaming patterns from production usage into the BranchName component:

Leading visual — a branch/tag icon before the name
Trailing action — copy button, branch switcher menu
Description tooltip — shows owner/repo:branch context

The proposal recommends Option A — Compound component based on analysis of github-ui usage patterns.

Changelog

New

API proposal document at packages/react/src/BranchName/BranchName.api-proposal.md

Changed

None

Removed

None

Rollout strategy

None; this is a proposal document only, no code changes

Testing & Reviewing

Review the proposal document for API design feedback.

Merge checklist

Demonstrate a trailing action pattern (copy button) for BranchName, serving as a reference for future implementation work. Add WithTrailingActionMenu story with SelectPanel Demonstrates branch switching via SelectPanel anchored to BranchName, showing the 'Change base branch' pattern. Remove overflow:hidden to prevent focus ring clipping

primer · 2026-06-15T14:36:14Z

🤖 Lint issues have been automatically fixed and committed to this PR.

- Add BranchName.LeadingVisual for branch/tag icons - Add BranchName.TrailingAction for copy/menu buttons - Add description prop for tooltip (aria-describedby) - Update stories to use new compound API - Add comprehensive tests for new API

…e-trailing-action-component # Conflicts: # packages/react/src/BranchName/BranchName.features.stories.tsx

- Merge BranchName.new-api.test.tsx into BranchName.test.tsx - Document description/className props and LeadingVisual/TrailingAction subcomponents - Refresh story ids in docs.json

primer · 2026-06-16T22:03:41Z

🤖 Lint issues have been automatically fixed and committed to this PR.

primer · 2026-06-16T22:09:36Z

🤖 Lint issues have been automatically fixed and committed to this PR.

primer · 2026-06-17T09:34:05Z

🤖 Lint issues have been automatically fixed and committed to this PR.

Copilot

Pull request overview

This PR evolves BranchName (in packages/react) from a simple link/text pill into a compound component API that supports a leading visual, a trailing action button, and an optional description tooltip, with corresponding styling, Storybook examples, test coverage, VRT snapshots, and a release changeset.

Changes:

Add BranchName.LeadingVisual and BranchName.TrailingAction slot subcomponents plus a description tooltip prop in BranchName.
Update CSS to support icon alignment and a trailing-action container layout.
Update Storybook “Features” stories, unit/type tests, and e2e VRT coverage; add a changeset.

Show a summary per file

File	Description
packages/react/src/BranchName/BranchName.tsx	Implements compound slot API (`LeadingVisual`, `TrailingAction`) and conditional description tooltip rendering.
packages/react/src/BranchName/BranchName.module.css	Switches to flex layout; adds styling for leading visual spacing and trailing-action wrapper/divider.
packages/react/src/BranchName/BranchName.features.stories.tsx	Updates stories to demonstrate the new compound API, description tooltip, and menu anchoring via `anchorRef`.
packages/react/src/BranchName/BranchName.docs.json	Documents the new `description` prop and subcomponents; expands referenced Storybook story IDs.
packages/react/src/BranchName/tests/BranchName.types.test.tsx	Updates type-level assertions to reflect the new `as` constraints and ref/event typing.
packages/react/src/BranchName/tests/BranchName.test.tsx	Adds unit tests for leading visual, trailing action behavior, and tooltip/aria-describedby behavior.
e2e/components/BranchName.test.ts	Expands VRT story coverage (including focus snapshots) for the new variants.
.changeset/whole-rings-glow.md	Adds a release note entry for the updated BranchName API.

Copilot's findings

Files reviewed: 8/71 changed files
Comments generated: 6

+  const {as: Component = 'a', className, children, description, ...rest} = props as BranchNameProps<'a'>
+
+  const [slots, textChildren] = useSlots(children, {
+    leadingVisual: LeadingVisual,
+    trailingAction: TrailingAction,
+  })
+
+  const link = (
+    <ConditionalTooltip description={description}>
+      <Component
+        {...rest}
+        ref={ref as React.Ref<HTMLAnchorElement>}
+        className={clsx(className, classes.BranchName)}


francinelucca · 2026-06-22T14:18:29Z

+export type BranchNameProps<As extends 'span' | 'a'> = PolymorphicProps<
  As,
  'a',
  {
    className?: string
+    /** Description tooltip text (renders as aria-describedby) */
+    description?: string
  }


Wondering about this, I found a few instances of other elements in dotcom

Very good catch to you both!

We definitely don't want to render a tooltip on an element that is not interactive. I'll see if we can add a typescript error and make that combination not allowed

okay, done! gonna test with dotcom first, because they look too clean to be correct 😅

      "name": "ref",
      "type": "React.RefObject<HTMLAnchorElement>"
    },
    {
      "name": "as",


+        {
+          "name": "className",
+          "type": "string",
+          "required": false,
+          "description": "A custom class name that is merged with the leading visual's class. Additional `span` props are forwarded to the underlying element.",
+          "defaultValue": ""
+        }


francinelucca

few comments/questions. Also noticed a mild css diff in the actionmenu story in the active state, not sure which one's correct:

Screen.Recording.2026-06-22.at.10.32.12.AM.mov

francinelucca · 2026-06-22T14:11:03Z

noticed some of these are displaying tooltips and some aren't, just want to make sure this doesn't become flaky vrt 👀

Yeah, I wanted to have screenshots for focus states and menu-open but it was creating too many screenshots, so I have limited interactive states to just light theme. Shouldn't be flaky in my opinion

francinelucca · 2026-06-22T14:18:29Z

+export type BranchNameProps<As extends 'span' | 'a'> = PolymorphicProps<
  As,
  'a',
  {
    className?: string
+    /** Description tooltip text (renders as aria-describedby) */
+    description?: string
  }


Wondering about this, I found a few instances of other elements in dotcom

francinelucca · 2026-06-22T14:20:11Z

+
+  // With a trailing action, render the action as a sibling of the link
+  return (
+    <span className={classes.BranchNameWithTrailingAction} data-component="BranchName.WrapperWithAction">


we don't do wrappers so this data-component is probably not needed

ack, removed.

francinelucca · 2026-06-22T14:27:16Z

-    <span className={styles.BranchNameWithTrailingAction}>
-      <BranchName href={`https://github.com/${repo}/tree/${selected.text}`} className={styles.BranchNameTransparent}>


any dead css as a result of this we can cleanup?

I thought I deleted the file, i had not 🤔 Thanks for catching that!

francinelucca · 2026-06-22T14:28:37Z

+    // Note: the story was renamed to "With Leading Visual" but we keep the
+    // snapshot title as "With A Branch Icon" so the VRT diff stays usable.


curious how this works 👀

Oh i just kept the title and filename the same in e2e/Branchname.test so that I can get a snapshot diff if there is one

…nent

siddharthkp · 2026-06-25T11:06:15Z

Also noticed a mild css diff in the actionmenu story in the active state, not sure which one's correct:

You found a big in AnchoredOverlay! I filed a detailed issue here (with copilot): https://github.com/github/primer/issues/6776

But, I'm surprised that VRT did not catch it though :/ Is the diff too tiny?

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

primer-integration · 2026-06-25T13:30:21Z

Integration test results from github/github-ui PR:

CI Failed
VRT Passed
Projects Passed

CI check runs linting, type checking, and unit tests. Check the workflow logs for specific failures.

Need help? If you believe this failure is unrelated to your changes, please reach out to the Primer team for assistance.

siddharthkp and others added 5 commits June 10, 2026 11:55

Add e2e tests for WithTrailingAction stories

aad16e8

test(vrt): update snapshots

fd4ede3

Use announce() instead of rendered Announce component

1a98046

Add BranchName API proposal

8d3071f

This comment was marked as resolved.

Sign in to view

github-actions Bot added staff Author is a staff member integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm labels Jun 15, 2026

This comment was marked as resolved.

Sign in to view

siddharthkp deployed to github-pages June 15, 2026 14:40 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7993 June 15, 2026 14:41 Inactive

siddharthkp changed the title ~~BranchName API proposal~~ Upstream BranchName features Jun 16, 2026

siddharthkp added 4 commits June 16, 2026 22:21

Implement BranchName compound API

21de126

- Add BranchName.LeadingVisual for branch/tag icons - Add BranchName.TrailingAction for copy/menu buttons - Add description prop for tooltip (aria-describedby) - Update stories to use new compound API - Add comprehensive tests for new API

Fix BranchName LeadingVisual vertical alignment

658a69b

Merge remote-tracking branch 'origin/main' into siddharthkp/branchnam…

1442a29

…e-trailing-action-component # Conflicts: # packages/react/src/BranchName/BranchName.features.stories.tsx

update changeset

25eda48

siddharthkp changed the title ~~Upstream BranchName features~~ BranchName: Add leadingVisual, trailingAction and description Jun 16, 2026

github-actions Bot requested a deployment to storybook-preview-7993 June 16, 2026 22:01 Abandoned

Consolidate BranchName tests and document compound API in docs.json

747843c

- Merge BranchName.new-api.test.tsx into BranchName.test.tsx - Document description/className props and LeadingVisual/TrailingAction subcomponents - Refresh story ids in docs.json

github-actions Bot requested a deployment to storybook-preview-7993 June 16, 2026 22:07 Abandoned

siddharthkp deployed to github-pages June 16, 2026 22:16 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7993 June 16, 2026 22:17 Inactive

siddharthkp added 2 commits June 17, 2026 11:27

Fix unnecessary optional chain lint error in BranchName

cfe2bb4

Remove BranchName API proposal doc

f74c96a

github-actions Bot requested a deployment to storybook-preview-7993 June 17, 2026 09:37 Abandoned

siddharthkp deployed to github-pages June 17, 2026 09:46 — with GitHub Actions View deployment

siddharthkp deployed to github-pages June 18, 2026 12:21 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7993 June 18, 2026 12:21 Inactive

siddharthkp marked this pull request as ready for review June 22, 2026 10:37

siddharthkp requested a review from a team as a code owner June 22, 2026 10:37

siddharthkp requested review from Copilot and joshblack June 22, 2026 10:37

Copilot started reviewing on behalf of siddharthkp June 22, 2026 10:38 View session

siddharthkp requested review from francinelucca and llastflowers and removed request for joshblack June 22, 2026 10:38

Copilot AI reviewed Jun 22, 2026

View reviewed changes

francinelucca reviewed Jun 22, 2026

View reviewed changes

Merge branch 'main' into siddharthkp/branchname-trailing-action-compo…

76f16c7

…nent

joshblack deployed to github-pages June 22, 2026 15:57 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7993 June 22, 2026 15:59 Inactive

siddharthkp and others added 3 commits June 25, 2026 13:24

Remove unused BranchName.stories.module.css

09cf7e1

Remove unused data-component from BranchName trailing action wrapper

62642f3

Potential fix for pull request finding

0da5d3a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

github-actions Bot temporarily deployed to storybook-preview-7993 June 25, 2026 11:35 Inactive

siddharthkp deployed to github-pages June 25, 2026 11:45 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7993 June 25, 2026 11:45 Inactive

BranchName: require href with description and forbid description on span

6f617f4

siddharthkp deployed to github-pages June 25, 2026 12:22 — with GitHub Actions View deployment

github-actions Bot temporarily deployed to storybook-preview-7993 June 25, 2026 12:22 Inactive

siddharthkp closed this Jun 25, 2026

siddharthkp reopened this Jun 25, 2026

siddharthkp deployed to github-pages June 25, 2026 13:03 — with GitHub Actions View deployment

github-actions Bot deployed to storybook-preview-7993 June 25, 2026 13:04 View deployment

		<span className={styles.BranchNameWithTrailingAction}>
		<BranchName href={`https://github.com/${repo}/tree/${selected.text}`} className={styles.BranchNameTransparent}>

		// Note: the story was renamed to "With Leading Visual" but we keep the
		// snapshot title as "With A Branch Icon" so the VRT diff stays usable.

Uh oh!

Conversation

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

Uh oh!

Changelog

New

Changed

Removed

Rollout strategy

Testing & Reviewing

Merge checklist

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

primer Bot commented Jun 15, 2026

Uh oh!

primer Bot commented Jun 16, 2026

Uh oh!

primer Bot commented Jun 16, 2026

Uh oh!

primer Bot commented Jun 17, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

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!

Uh oh!

Uh oh!

francinelucca left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

siddharthkp Jun 25, 2026 • 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!

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 Jun 25, 2026 • 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!

Uh oh!

siddharthkp commented Jun 25, 2026

Uh oh!

primer-integration Bot commented Jun 25, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

siddharthkp commented Jun 15, 2026 •

edited

Loading

siddharthkp Jun 25, 2026 •

edited

Loading

siddharthkp Jun 25, 2026 •

edited

Loading