Skip to content

perf(PageHeader): replace 18 :has() selectors with hoisted data attributes #7901

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mattcosta7 wants to merge 4 commits into
base: main
Choose a base branch
from
Open

perf(PageHeader): replace 18 :has() selectors with hoisted data attributes #7901

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8e4a4bd
perf(PageHeader): replace 18 :has() selectors with hoisted data attri…
mattcosta7 May 29, 2026
79cbb1c
handle nesting
mattcosta7 Jun 1, 2026
88cda5e
Apply suggestion from @mattcosta7
mattcosta7 Jun 1, 2026
6001d9f
refactor(PageHeader): return hoisted child state to fix TS narrowing
mattcosta7 Jun 1, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/perf-pageheader-has-selectors.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
'@primer/react': patch
---

PageHeader: hoist title-size and navigation-visibility state from descendants onto the root and replace 18 `:has()` selectors with plain attribute selectors. Same rendered output; the engine no longer re-evaluates subtree-scoped `:has()` selectors on every DOM mutation inside a `PageHeader`.
40 changes: 21 additions & 19 deletions packages/react/src/PageHeader/PageHeader.module.css
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,25 +33,28 @@
line-height is calculated with calc(height/font-size) and the below numbers are from @primer/primitives.
--custom-font-size, --custom-line-height, --custom-font-weight are custom properties that can be used to override the below values.
We don't want these values to be overridden but still want to allow consumers to override them if needed.

Size + nav-visibility data attributes are hoisted to the root by the React
component to keep selectors as plain attribute matches (cheap) rather than
relying on `:has()` (per-descendant invalidation).
*/
/* stylelint-disable selector-pseudo-class-disallowed-list -- :has() scoped to CSS Module, audited (github/github-ui#17224) */
&:has([data-component='TitleArea'][data-size-variant='large']) {
&[data-title-size-variant='large'] {
font-size: var(--custom-font-size, var(--text-title-size-large, 2rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5)); /* calc(48/32) */

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));
}

&:has([data-component='TitleArea'][data-size-variant='medium']) {
&[data-title-size-variant='medium'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-semibold, 600));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6)); /* calc(32/20) */

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
}

&:has([data-component='TitleArea'][data-size-variant='subtitle']) {
&[data-title-size-variant='subtitle'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6)); /* calc(32/20) */
Expand All @@ -61,23 +64,23 @@

/* Responsive size variants */
@media (--viewportRange-narrow) {
&:has([data-component='TitleArea'][data-size-variant-narrow='large']) {
&[data-title-size-variant-narrow='large'] {
font-size: var(--custom-font-size, var(--text-title-size-large, 2rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));
}

&:has([data-component='TitleArea'][data-size-variant-narrow='medium']) {
&[data-title-size-variant-narrow='medium'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-semibold, 600));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
}

&:has([data-component='TitleArea'][data-size-variant-narrow='subtitle']) {
&[data-title-size-variant-narrow='subtitle'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
Expand All @@ -87,23 +90,23 @@
}

@media (--viewportRange-regular) {
&:has([data-component='TitleArea'][data-size-variant-regular='large']) {
&[data-title-size-variant-regular='large'] {
font-size: var(--custom-font-size, var(--text-title-size-large, 2rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));
}

&:has([data-component='TitleArea'][data-size-variant-regular='medium']) {
&[data-title-size-variant-regular='medium'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-semibold, 600));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
}

&:has([data-component='TitleArea'][data-size-variant-regular='subtitle']) {
&[data-title-size-variant-regular='subtitle'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
Expand All @@ -113,23 +116,23 @@
}

@media (--viewportRange-wide) {
&:has([data-component='TitleArea'][data-size-variant-wide='large']) {
&[data-title-size-variant-wide='large'] {
font-size: var(--custom-font-size, var(--text-title-size-large, 2rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-large, 1.5));
}

&:has([data-component='TitleArea'][data-size-variant-wide='medium']) {
&[data-title-size-variant-wide='medium'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-semibold, 600));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));

--title-line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
}

&:has([data-component='TitleArea'][data-size-variant-wide='subtitle']) {
&[data-title-size-variant-wide='subtitle'] {
font-size: var(--custom-font-size, var(--text-title-size-medium, 1.25rem));
font-weight: var(--custom-font-weight, var(--base-text-weight-normal, 400));
line-height: var(--custom-line-height, var(--text-title-lineHeight-medium, 1.6));
Expand All @@ -138,33 +141,32 @@
}
}

&[data-has-border='true']:has([data-component='PH_Navigation'][data-hidden-all]),
&[data-has-border='true']:not(:has([data-component='PH_Navigation'])) {
&[data-has-border='true'][data-nav-hidden-all],
&[data-has-border='true']:not([data-has-nav]) {
border-block-end: var(--borderWidth-thin) solid var(--borderColor-default);
padding-block-end: var(--base-size-8);
}

@media (--viewportRange-narrow) {
&[data-has-border='true']:has([data-component='PH_Navigation'][data-hidden-narrow]) {
&[data-has-border='true'][data-nav-hidden-narrow] {
border-block-end: var(--borderWidth-thin) solid var(--borderColor-default);
padding-block-end: var(--base-size-8);
}
}

@media (--viewportRange-regular) {
&[data-has-border='true']:has([data-component='PH_Navigation'][data-hidden-regular]) {
&[data-has-border='true'][data-nav-hidden-regular] {
border-block-end: var(--borderWidth-thin) solid var(--borderColor-default);
padding-block-end: var(--base-size-8);
}
}

@media (--viewportRange-wide) {
&[data-has-border='true']:has([data-component='PH_Navigation'][data-hidden-wide]) {
&[data-has-border='true'][data-nav-hidden-wide] {
border-block-end: var(--borderWidth-thin) solid var(--borderColor-default);
padding-block-end: var(--base-size-8);
}
}
/* stylelint-enable selector-pseudo-class-disallowed-list */

& [data-component='PH_LeadingAction'],
& [data-component='PH_TrailingAction'],
Expand Down
100 changes: 100 additions & 0 deletions packages/react/src/PageHeader/PageHeader.test.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -111,4 +111,104 @@ describe('PageHeader', () => {
)
expect(container.firstChild).toHaveAttribute('aria-label', 'Custom aria-label')
})

describe('hoisted root data attributes', () => {
it('hoists the TitleArea variant onto the root as "data-title-size-variant"', () => {
const {container} = render(
<PageHeader role="banner">
<PageHeader.TitleArea variant="large">
<PageHeader.Title>Title</PageHeader.Title>
</PageHeader.TitleArea>
</PageHeader>,
)
expect(container.firstChild).toHaveAttribute('data-title-size-variant', 'large')
})

it('defaults the hoisted "data-title-size-variant" to "medium" when TitleArea has no variant', () => {
const {container} = render(
<PageHeader role="banner">
<PageHeader.TitleArea>
<PageHeader.Title>Title</PageHeader.Title>
</PageHeader.TitleArea>
</PageHeader>,
)
expect(container.firstChild).toHaveAttribute('data-title-size-variant', 'medium')
})

it('hoists the TitleArea variant through fragment wrappers', () => {
const {container} = render(
<PageHeader role="banner">
<>
<PageHeader.TitleArea variant="large">
<PageHeader.Title>Title</PageHeader.Title>
</PageHeader.TitleArea>
</>
</PageHeader>,
)
expect(container.firstChild).toHaveAttribute('data-title-size-variant', 'large')
})

it('does not emit "data-title-size-variant" when no TitleArea is rendered', () => {
const {container} = render(
<PageHeader role="banner">
<PageHeader.Navigation as="nav" aria-label="Custom">
Navigation
</PageHeader.Navigation>
</PageHeader>,
)
expect(container.firstChild).not.toHaveAttribute('data-title-size-variant')
})

it('emits "data-has-nav" on the root when a Navigation child is rendered', () => {
const {container} = render(
<PageHeader role="banner">
<PageHeader.TitleArea>
<PageHeader.Title>Title</PageHeader.Title>
</PageHeader.TitleArea>
<PageHeader.Navigation as="nav" aria-label="Custom">
Navigation
</PageHeader.Navigation>
</PageHeader>,
)
expect(container.firstChild).toHaveAttribute('data-has-nav')
})

it('hoists a Navigation child through fragment wrappers', () => {
const {container} = render(
<PageHeader role="banner">
<>
<PageHeader.Navigation as="nav" aria-label="Custom">
Navigation
</PageHeader.Navigation>
</>
</PageHeader>,
)
expect(container.firstChild).toHaveAttribute('data-has-nav')
})

it('does not emit "data-has-nav" on the root when no Navigation child is rendered', () => {
const {container} = render(
<PageHeader role="banner">
<PageHeader.TitleArea>
<PageHeader.Title>Title</PageHeader.Title>
</PageHeader.TitleArea>
</PageHeader>,
)
expect(container.firstChild).not.toHaveAttribute('data-has-nav')
})

it('hoists the Navigation hidden state onto the root as "data-nav-hidden-*"', () => {
const {container} = render(
<PageHeader role="banner">
<PageHeader.TitleArea>
<PageHeader.Title>Title</PageHeader.Title>
</PageHeader.TitleArea>
<PageHeader.Navigation as="nav" aria-label="Custom" hidden={{narrow: true, regular: false, wide: false}}>
Navigation
</PageHeader.Navigation>
</PageHeader>,
)
expect(container.firstChild).toHaveAttribute('data-nav-hidden-narrow', 'true')
})
})
})
70 changes: 59 additions & 11 deletions packages/react/src/PageHeader/PageHeader.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,43 @@ const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeader
({children, className, as: BaseComponent = 'div', 'aria-label': ariaLabel, role, hasBorder}, forwardedRef) => {
const rootRef = useProvidedRefOrCreate<HTMLDivElement>(forwardedRef as React.RefObject<HTMLDivElement>)

// Hoist title size + navigation visibility off children onto the root so
// styling can use plain attribute selectors instead of `:has()`. We descend
// into fragments so this matches the previous DOM-based `:has()` selectors,
// which saw through fragment wrappers. `titleVariant` stays undefined when
// no TitleArea is rendered so the root doesn't emit title sizing in that case.
//
// We return the hoisted state (rather than mutating closure variables) so
// TypeScript's control-flow analysis keeps the correct types at the usage
// sites below — a value mutated inside a closure stays narrowed to its
// initializer (e.g. `hasNavigation` would otherwise be typed as `false`).
type HoistedChildState = {
titleVariant?: TitleAreaProps['variant']
hasNavigation: boolean
navigationHidden?: NavigationProps['hidden']
}
const hoistChildState = (nodes: React.ReactNode): HoistedChildState => {
const result: HoistedChildState = {hasNavigation: false}
for (const child of React.Children.toArray(nodes)) {
if (!React.isValidElement(child)) continue
if (child.type === React.Fragment) {
const nested = hoistChildState((child.props as {children?: React.ReactNode}).children)
if (nested.titleVariant !== undefined) result.titleVariant = nested.titleVariant
if (nested.hasNavigation) {
result.hasNavigation = true
result.navigationHidden = nested.navigationHidden
}
} else if (child.type === TitleArea) {
result.titleVariant = (child.props as TitleAreaProps).variant ?? 'medium'
} else if (child.type === Navigation) {
result.hasNavigation = true
result.navigationHidden = (child.props as NavigationProps).hidden ?? false
}
}
return result
}
const {titleVariant, hasNavigation, navigationHidden} = hoistChildState(children)

const isInteractive = (element: HTMLElement) => {
return (
['a', 'button'].some(selector => element.matches(selector)) ||
Expand Down Expand Up @@ -108,6 +145,9 @@ const Root = React.forwardRef<HTMLDivElement, React.PropsWithChildren<PageHeader
ref={rootRef}
className={clsx(classes.PageHeader, className)}
data-has-border={hasBorder ? 'true' : undefined}
data-has-nav={hasNavigation ? '' : undefined}
{...getResponsiveAttributes('title-size-variant', titleVariant)}
{...getNavHiddenDataAttributes(navigationHidden)}
aria-label={ariaLabel}
role={role}
>
Expand Down Expand Up @@ -374,41 +414,44 @@ const Navigation: React.FC<React.PropsWithChildren<NavigationProps>> = ({

// Based on getBreakpointDeclarations, this function will return the
// correct data attribute for the given hidden value for CSS modules.
function getHiddenDataAttributes(isHidden: boolean | ResponsiveValue<boolean>): {
'data-hidden-all'?: boolean
'data-hidden-narrow'?: boolean
'data-hidden-regular'?: boolean
'data-hidden-wide'?: boolean
} {
function getHiddenDataAttributes(
isHidden: boolean | ResponsiveValue<boolean>,
prefix: 'hidden' | 'nav-hidden' = 'hidden',
): Record<string, boolean | undefined> {
const all = `data-${prefix}-all`
const narrow = `data-${prefix}-narrow`
const regular = `data-${prefix}-regular`
const wide = `data-${prefix}-wide`

if (isResponsiveValue(isHidden)) {
const responsiveValue = isHidden

// Build media queries with the giving cssProperty and mapFn
const narrowMediaQuery =
'narrow' in responsiveValue
? {
'data-hidden-narrow': responsiveValue.narrow || undefined,
[narrow]: responsiveValue.narrow || undefined,
}
: {}

const regularMediaQuery =
'regular' in responsiveValue
? {
'data-hidden-regular': responsiveValue.regular || undefined,
[regular]: responsiveValue.regular || undefined,
}
: {}

const wideMediaQuery =
'wide' in responsiveValue
? {
'data-hidden-wide': responsiveValue.wide || undefined,
[wide]: responsiveValue.wide || undefined,
}
: {}

// check if all values are the same - this is not a recommended practice but we still should check for it
if (areAllValuesTheSame(responsiveValue)) {
// if all the values are the same, we can just use one of the value to determine the CSS property's value
return {'data-hidden-all': responsiveValue.narrow || undefined}
return {[all]: responsiveValue.narrow || undefined}
// check if regular and wide have the same value, if so we can just return the narrow and regular media queries
} else if (haveRegularAndWideSameValue(responsiveValue)) {
return {
Expand All @@ -424,10 +467,15 @@ function getHiddenDataAttributes(isHidden: boolean | ResponsiveValue<boolean>):
}
} else {
// If the given value is not a responsive value
return {'data-hidden-all': isHidden || undefined}
return {[all]: isHidden || undefined}
}
}

function getNavHiddenDataAttributes(isHidden: boolean | ResponsiveValue<boolean> | undefined) {
if (isHidden === undefined) return undefined
return getHiddenDataAttributes(isHidden, 'nav-hidden')
}

export const PageHeader = Object.assign(Root, {
ContextArea,
ParentLink,
Expand Down
Loading