BranchName: Add `leadingVisual`, `trailingAction` and `description`#7993

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:28:37Z

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

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

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

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

-Original file line number
+Diff line change
@@ -0,0 +1,5 @@
+---
+"@primer/react": minor
+---
+BranchName: Add `LeadingVisual` and `TrailingAction` subcomponents and a `description` prop

-Original file line number
+Diff line change
@@ Expand Up / @@ -14,10 +14,27 @@ const stories = [ @@
  focus: false,
  },
  {
+ // 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.
  title: 'With A Branch Icon',
- id: 'components-branchname-features--with-branch-icon',
+ id: 'components-branchname-features--with-leading-visual',
  focus: false,
  },
+ {
+ title: 'Link Without Href',
+ id: 'components-branchname-features--link-without-href',
+ focus: true,
+ },
+ {
+ title: 'No Props',
+ id: 'components-branchname-features--no-props',
+ focus: false,
+ },
+ {
+ title: 'With Description',
+ id: 'components-branchname-features--with-description',
+ focus: true,
+ },
  {
  title: 'With Trailing Action',
  id: 'components-branchname-features--with-trailing-action',
@@ Expand All / @@ -28,6 +45,11 @@ const stories = [ @@
  id: 'components-branchname-features--with-trailing-action-menu',
  focus: false,
  },
+ {
+ title: 'Kitchen Sink',
+ id: 'components-branchname-features--kitchen-sink',
+ focus: false,
+ },
 ] as const
 test.describe('BranchName', () => {
@@ Expand Down @@

-Original file line number
+Diff line change
@@ Expand Up / @@ -8,7 +8,16 @@ @@
  "id": "components-branchname--default"
  },
  {
- "id": "components-branchname-features--with-branch-icon"
+ "id": "components-branchname-features--with-leading-visual"
+ },
+ {
+ "id": "components-branchname-features--with-description"
+ },
+ {
+ "id": "components-branchname-features--with-trailing-action"
+ },
+ {
+ "id": "components-branchname-features--with-trailing-action-menu"
  },
  {
  "id": "components-branchname-features--not-a-link"
@@ Expand All / @@ -24,7 +33,88 @@ @@
  "name": "as",
  "type": "React.ElementType",
  "defaultValue": "\"a\""
+ },
+ {
+ "name": "children",
+ "type": "React.ReactNode",
+ "required": false,
+ "description": "The branch name, optionally including BranchName.LeadingVisual and BranchName.TrailingAction subcomponents.",
+ "defaultValue": ""
+ },
+ {
+ "name": "description",
+ "type": "string",
+ "required": false,
+ "description": "Description tooltip text. Provides additional context for the branch name and is exposed to assistive technology via `aria-describedby`.",
+ "defaultValue": ""
+ },
+ {
+ "name": "className",
+ "type": "string",
+ "required": false,
+ "description": "Custom className",
+ "defaultValue": ""
  }
  ],
- "subcomponents": []
+ "subcomponents": [
+ {
+ "name": "BranchName.LeadingVisual",
+ "props": [
+ {
+ "name": "children",
+ "type": "React.ReactNode",
+ "required": false,
+ "description": "The leading visual content, typically an octicon. We recommend using `GitBranchIcon` to represent a branch.",
+ "defaultValue": ""
+ },
+ {
+ "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": ""
+ }
+ ]
+ },
+ {
+ "name": "BranchName.TrailingAction",
+ "props": [
+ {
+ "name": "icon",
+ "type": "React.ComponentType",
+ "required": true,
+ "description": "Provide an octicon. It will be placed in the center of the action button.",
+ "defaultValue": ""
+ },
+ {
+ "name": "aria-label",
+ "type": "string",
+ "required": true,
+ "description": "Use an aria label to describe the functionality of the button. Please refer to [our guidance on alt text](https://primer.style/guides/accessibility/alternative-text-for-images) for tips on writing good alternative text.",
+ "defaultValue": ""
+ },
+ {
+ "name": "onClick",
+ "type": "React.MouseEventHandler<HTMLButtonElement>",
+ "required": false,
+ "description": "Handler called when the trailing action button is clicked.",
+ "defaultValue": ""
+ },
+ {
+ "name": "className",
+ "type": "string",
+ "required": false,
+ "description": "A custom class name that is merged with the action button's class. Additional `button` props are forwarded to the underlying button.",
+ "defaultValue": ""
+ },
+ {
+ "name": "ref",
+ "type": "React.RefObject<HTMLButtonElement>",
+ "required": false,
+ "description": "A ref forwarded to the underlying action button.",
+ "defaultValue": ""
+ }
+ ]
+ }
+ ]
 }

-Original file line number
+Diff line change
@@ -1,29 +1,22 @@
 import type {Meta} from '@storybook/react-vite'
-import React, {useState} from 'react'
+import React, {useState, useRef} from 'react'
 import BranchName from './BranchName'
-import {Stack} from '../Stack'
-import Octicon from '../Octicon'
 import {GitBranchIcon, CopyIcon, CheckIcon, TriangleDownIcon} from '@primer/octicons-react'
-import {IconButton} from '../Button'
-import {Tooltip} from '../TooltipV2'
 import {SelectPanel} from '../SelectPanel'
 import type {ItemInput} from '../FilteredActionList'
-import {clsx} from 'clsx'
 import {announce} from '@primer/live-region-element'
-import styles from './BranchName.stories.module.css'
 export default {
  title: 'Components/BranchName/Features',
  component: BranchName,
 } as Meta<typeof BranchName>
-export const WithBranchIcon = () => (
+export const WithLeadingVisual = () => (
  <BranchName href="#">
- <Stack direction="horizontal" gap="condensed" align="center">
- <Octicon icon={GitBranchIcon} />
- branch_name
-</Stack>
+ <BranchName.LeadingVisual>
+ <GitBranchIcon />
+</BranchName.LeadingVisual>
+branch_name
  </BranchName>
 )
@@ Expand All / @@ -38,6 +31,18 @@ export const LinkWithoutHref = () => ( @@
 export const NoProps = () => <BranchName>branch_name_no_props</BranchName>
+export const WithDescription = ({
+ branchName = 'fix/anchored-overlay-outside-top-autogrow',
+ repo = 'primer/react',
+}: {
+ branchName: string
+ repo: string
+}) => (
+ <BranchName href={`https://github.com/${repo}/tree/${branchName}`} description={`${repo}:${branchName}`}>
+ {branchName}
+ </BranchName>
+)
 export const WithTrailingAction = ({
  branchName = 'fix/anchored-overlay-outside-top-autogrow',
  repo = 'primer/react',
@@ Expand All / @@ -54,26 +59,15 @@ export const WithTrailingAction = ({ @@
  setTimeout(() => setCopied(false), 2000)
  }
- const tooltipText = copied ? 'Copied!' : 'Copy branch name to clipboard'
  return (
- <span className={styles.BranchNameWithTrailingAction}>
- <Tooltip text={`${repo}:${branchName}`}>
- <BranchName href={`https://github.com/${repo}/tree/${branchName}`} className={styles.BranchNameTransparent}>
- {branchName}
- </BranchName>
- </Tooltip>
- <Tooltip text={tooltipText} aria-hidden>
- <IconButton
- icon={copied ? CheckIcon : CopyIcon}
- aria-label="Copy branch name to clipboard"
- variant="invisible"
- size="small"
- onClick={handleCopy}
- className={clsx(styles.TrailingActionButton, copied && styles.TrailingActionButtonCopied)}
- />
- </Tooltip>
- </span>
+ <BranchName href={`https://github.com/${repo}/tree/${branchName}`} description={`${repo}:${branchName}`}>
+ {branchName}
+ <BranchName.TrailingAction
+ icon={copied ? CheckIcon : CopyIcon}
+ aria-label="Copy branch name to clipboard"
+ onClick={handleCopy}
+ />
+ </BranchName>
  )
 }
@@ Expand All @@
  const [selected, setSelected] = useState<ItemInput>(branches[0])
  const [filter, setFilter] = useState('')
  const [open, setOpen] = useState(false)
+ const anchorRef = useRef<HTMLButtonElement>(null)
  const filteredBranches = branches.filter(branch => branch.text?.toLowerCase().includes(filter.toLowerCase()))
@@ Expand All @@
  }
  return (
- <span className={styles.BranchNameWithTrailingAction}>
- <BranchName href={`https://github.com/${repo}/tree/${selected.text}`} className={styles.BranchNameTransparent}>
+ <>
+ <BranchName href={`https://github.com/${repo}/tree/${selected.text}`}>
  {selected.text}
+ <BranchName.TrailingAction
+ icon={TriangleDownIcon}
+ aria-label="Change base branch"
+ ref={anchorRef}
+ onClick={() => setOpen(!open)}
+ />
  </BranchName>
  <SelectPanel
- renderAnchor={anchorProps => (
- <IconButton
- icon={TriangleDownIcon}
- aria-label="Change base branch"
- variant="invisible"
- size="small"
- className={styles.TrailingActionButton}
- {...anchorProps}
- />
- )}
+ renderAnchor={null}
+ anchorRef={anchorRef}
  placeholder="Find a branch..."
  open={open}
  onOpenChange={setOpen}
@@ Expand All @@
  title="Change base branch"
  overlayProps={{width: 'medium'}}
  />
- </span>
+ </>
+ )
+}
+export const KitchenSink = ({
+ branchName = 'fix/anchored-overlay-outside-top-autogrow',
+ repo = 'primer/react',
+}: {
+ branchName: string
+ repo: string
+}) => {
+ const [copied, setCopied] = React.useState(false)
+ const handleCopy = () => {
+ setCopied(true)
+ void navigator.clipboard.writeText(branchName)
+ announce('Copied!')
+ setTimeout(() => setCopied(false), 2000)
+ }
+ return (
+ <BranchName href={`https://github.com/${repo}/tree/${branchName}`} description={`${repo}:${branchName}`}>
+ <BranchName.LeadingVisual>
+ <GitBranchIcon />
+ </BranchName.LeadingVisual>
+ {branchName}
+ <BranchName.TrailingAction
+ icon={copied ? CheckIcon : CopyIcon}
+ aria-label="Copy branch name to clipboard"
+ onClick={handleCopy}
+ />
+ </BranchName>
  )
 }

-Original file line number
+Diff line change
@@ -1,5 +1,6 @@
 .BranchName {
- display: inline-block;
+ display: inline-flex;
+ align-items: center;
  padding: var(--base-size-2) var(--base-size-6);
  font-family: var(--fontStack-monospace);
  font-size: var(--text-body-size-small);
@@ Expand All / @@ -11,4 +12,63 @@ @@
  &:is(:not(a)) {
  color: var(--fgColor-muted);
  }
+ [data-component='BranchName.LeadingVisual'] {
+ display: inline-flex;
+ align-items: center;
+ margin-inline-end: var(--base-size-4);
+ }
+}
+/* Container for BranchName with trailing actions */
+.BranchNameWithTrailingAction {
+ display: inline-flex;
+ align-items: stretch;
+ /* Create room for pseudo-border divider */
+ gap: var(--borderWidth-default);
+ flex-wrap: nowrap;
+ /* Moving the background to the container allows stacking the button hover background over it */
+ background-color: var(--bgColor-accent-muted);
+ border-radius: var(--borderRadius-medium);
+ [data-component='BranchName'] {
+ background-color: transparent;
+ }
+ [data-component='BranchName.TrailingAction'] {
+ display: inline-flex;
+ align-items: stretch;
+ }
+ [data-component='IconButton'] {
+ /* Make the size auto calculated based on icon size and padding */
+ height: auto;
+ width: auto;
+ padding: var(--base-size-2) var(--base-size-6);
+ position: relative;
+ align-items: center;
+ &:not(:disabled, [aria-disabled='true']) {
+ --button-invisible-iconColor-rest: var(--fgColor-link);
+ }
+ [data-component='Octicon'] {
+ /* Set icon size to text size to exactly match the branch name component */
+ height: var(--text-body-size-small);
+ width: var(--text-body-size-small);
+ }
+ /* Dividing line between button and name. */
+ &::before {
+ content: '';
+ position: absolute;
+ width: var(--borderWidth-default);
+ /* Position _between_ items (offsetting by width) to avoid overlapping with the real button border on hover/focus */
+ inset: var(--base-size-4) auto var(--base-size-4) calc(-1 * var(--borderWidth-default));
+ /* we want a divider/border but are using background color to make that happen */
+ /* stylelint-disable-next-line primer/colors */
+ background-color: var(--borderColor-accent-muted);
+ }
+ }
 }

Uh oh!

BranchName: Add leadingVisual, trailingAction and description#7993

Are you sure you want to change the base?

Uh oh!

BranchName: Add leadingVisual, trailingAction and description#7993

Uh oh!

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

francineluccaJun 22, 2026

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

francineluccaJun 22, 2026

Choose a reason for hiding this comment

Uh oh!

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

francineluccaJun 22, 2026

Choose a reason for hiding this comment

Uh oh!

siddharthkpJun 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

BranchName: Add `leadingVisual`, `trailingAction` and `description`#7993

BranchName: Add `leadingVisual`, `trailingAction` and `description`#7993

siddharthkpJun 25, 2026•
edited
Loading

siddharthkpJun 25, 2026•
edited
Loading