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.

…ual slots

…wrapping LeadingVisual and TrailingAction now accept rest props and merge className. Collapse the description-tooltip branches into a single ConditionalTooltip render path.

primer · 2026-06-18T11:46:46Z

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

…any ref

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

      "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": ""
+        }


+"@primer/react": minor
+---
+
+BranchName: Add `leadingVisual`, `trailingAction` and `description` prop


+---
+"@primer/react": minor
+---
+
+BranchName: Add `leadingVisual`, `trailingAction` and `description` prop


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 👀

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

francinelucca · 2026-06-22T14:26:41Z

-    <Stack direction="horizontal" gap="condensed" align="center">
-      <Octicon icon={GitBranchIcon} />
-      branch_name
-    </Stack>


is the previous way still supported? just making sure this isn't a breaking change

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?

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 👀

francinelucca · 2026-06-22T14:31:38Z

double-checking that the change in spacing here is expected

…nent

primer-integration · 2026-06-22T16:22:18Z

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

Make BranchName.LeadingVisual children-only to match other LeadingVis…

7749254

…ual slots

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

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

BranchName: forward props/merge className on slots, simplify tooltip …

7397e5f

…wrapping LeadingVisual and TrailingAction now accept rest props and merge className. Collapse the description-tooltip branches into a single ConditionalTooltip render path.

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

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

siddharthkp and others added 2 commits June 18, 2026 13:40

manual refactor

a4553a2

chore: auto-fix lint and formatting issues

1d876f4

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

refactor(BranchName): narrow polymorphic 'as' to span | a and remove …

203aa28

…any ref

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

test(BranchName): update types test for narrowed span | a polymorphism

c3804a3

github-actions Bot requested a deployment to storybook-preview-7993 June 18, 2026 12:11 Abandoned

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 deployed to storybook-preview-7993 June 22, 2026 15:59 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.

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!

primer Bot commented Jun 18, 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!

francinelucca 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!

primer-integration Bot commented Jun 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

siddharthkp commented Jun 15, 2026 •

edited

Loading