Components: Update polymorphism types to allow all attributes when specifying `as` by aduth · Pull Request #80705 · WordPress/gutenberg

aduth · 2026-07-24T20:02:05Z

What?

Updates the polymorphism types used in @wordpress/components to expose all possible HTML attributes when as is specified, rather than narrowing the types based on the tagName provided to as.

The performance impact on TypeScript builds is significant, reducing memory usage by -47% (7.4GB to 4.0GB), TypeScript build time by -49% (13.7s to 7.0s), and internal instantiations by -54% (42.5M to 19.5M).

Why?

Significant performance improvement and reduced memory usage.
Improves build stability.
- Recently, builds have been crashing during TypeScript compilation (example). This was discussed in Slack and Components: Skip polymorphism prop typings on intersection #80364 was aimed at improving this, but the issue persists. It was known with Components: Skip polymorphism prop typings on intersection #80364 that the "peak memory usage" was not dramatically reduced, and so TypeScript builds could still consume more than 10GB of memory, likely exhausting the CI environment.

How?

As described in #80655 , these polymorphism types are a major contributor to overall TypeScript build times and memory consumption. While #80655 tried to fully maintain the original intent of the polymorphism types, the changes here propose a more drastic change: If as is provided, all valid HTML attributes are accessible on that component. This means someone could do something like <VisuallyHidden as="div" htmlFor="id" /> and TypeScript would consider it valid, which was not the case before now, as htmlFor is not a valid attribute for div elements.

This is meant to be a reasonable compromise given the circumstances, and how new development in @wordpress/ui leans on render props instead of as polymorphism. render props don't suffer from this problem because props which are relevant to the component passed to render are applied to the element directly.

This isn't all bad though, since:

Those additional HTML attributes only become known if as is provided, and otherwise the component's own props are the only ones available.
The attribute types are still accurately typed, so TypeScript validates that htmlFor is a string, for example.

Testing Instructions

Verify type-checking passes:

npm run build

For bonus points, try some of the scenarios described under "How", like how you can't assign htmlFor unless specifying as, or that htmlFor can be used with as="div", or how htmlFor can't be assigned to a type other than string.

Also check performance for yourself using snippets from #80364 "Testing Instructions":

If you want to validate performance yourself, you can compare the following set of commands on this branch and trunk:

rm -f packages/components/tsconfig.tsbuildinfo
/usr/bin/time -l npx tsc -p packages/components/tsconfig.json --extendedDiagnostics 2>&1 \
  | grep -E '^(Symbols|Instantiations|Memory used|Memory allocs):|maximum resident'

Or full project timings and memory usage:

npx tsc --build --clean >/dev/null 2>&1
rm -rf packages/*/build-types
/usr/bin/time -l npx tsc --build 2>&1 | grep -E 'maximum resident|real'

Use of AI Tools

Used Cursor IDE + Auto (likely Composer) model to research and implement, with manual iterations, particularly on the code comments.

github-actions · 2026-07-24T20:07:03Z

Size Change: -7 B (0%)

Total Size: 7.76 MB

📦 View Changed

Filename	Size	Change
`build/scripts/preferences/index.min.js`	3.3 kB	-7 B (-0.21%)

_{compressed-size-action}

aduth · 2026-07-24T20:07:33Z

+	/**
+	 * The content to render inside the wrapper.
+	 */
+	children?: ReactNode;


From what I understand, this should have always been here, and the previous polymorphism types incorrectly typed children for non-polymorphic components. Generally it should be expected that components define their own children types, which we're more consistent about in @wordpress/ui (e.g. ComponentProps explicitly omits children)

github-actions · 2026-07-24T20:07:43Z

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org>
Co-authored-by: mirka <0mirka00@git.wordpress.org>
Co-authored-by: tyxla <tyxla@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

aduth · 2026-07-24T20:08:37Z

Oof, type-checking failures in CI. Guessing some local cache might have misled me locally. I'll throw this back to draft temporarily and revisit it on Monday, unless someone wants to go ahead and carry the torch on this one.

Edit: Nevermind, decided to tackle it now.

aduth · 2026-07-24T20:30:16Z

 											path={ `/${ tab.name }` }
-											// @ts-expect-error: Navigator.Button is currently typed in a way that prevents Item from being passed in
 											as={ Item }
-											isAction


This is safe:

gutenberg/packages/components/CHANGELOG.md

Line 3309 in c6c8e71

- Removed `isAction` prop from `Item`. The component will now rely on `onClick` to render as a `button` ([35152](https://github.com/WordPress/gutenberg/pull/35152)).

Navigator.Button provides onClick:

gutenberg/packages/components/src/navigator/navigator-button/hook.ts

Line 50 in c6c8e71

onClick: handleClick,

The reason the removal has to happen is because the TypeScript error on the line above assigning as={ Item } no longer errors, and the suppression through @ts-expect-error was subsequently not checking this prop, which had been removed from the types in #35152. Once the props were checked, it flagged the prop as not part of the Item props types.

github-actions · 2026-07-24T21:10:55Z

Flaky tests detected in 7e5d36a.
Some tests passed with failed attempts. The failures may not be related to this commit but are still reported for visibility. See the documentation for more information.

🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/30124455510
📝 Reported issues:

[Flaky Test] Should insert content using the global inserter #78924 in /test/e2e/specs/widgets/editing-widgets.spec.js

tyxla · 2026-07-27T13:40:06Z

Wow, nice work @aduth. This will likely greatly improve the performance of extenders of @wordpress/components that historically have suffered from slow builds or even OOMs when extending @wordpress/components types more aggressively.

manzoorwanijk

Thank you for improving the performance here. I have some inline questions/suggestions.

Also, I was wondering whether we should have some type tests for the usages.

manzoorwanijk · 2026-07-28T04:37:35Z

+ * Compatible with Emotion/`styled` `as` props and React's `ElementType`, without
+ * using the default `React.ElementType` mapped type helper directly.
+ */
+type PolymorphicAs =


Should this be named something that explains what it actually is rather than what it's used for? Like PolymorphicElement, PolymorphicElementType etc.

Sure, that does seem better 👍

Also worth noting that this separate type should ideally be temporary, as there's a lot of active work underway to eliminate Emotion altogether (#66806), at which point we won't need this.

at which point we won't need this

I think we do? Unless we get rid of the as prop back compat. (We're removing Emotion, but keeping the as prop for back compat.)

I dug into this a bit more. I understood that we would continue supporting as, but it was my impression from rounds of iteration with my AI agent that there was something specific about Emotion's typings that made it necessary to type it this way specifically. But on closer examination, I think my agent made an inappropriate leap based on trying to simplify this typing to something like as?: string | React.JSXElementConstructor< any > as the ideal end-case, and the only thing holding us up was Emotion's stricter treatment of keyof React.JSX.IntrinsicElements vs. string. I think this isn't so much an "Emotion" thing as it is just better more accurate types. It's a little bit of a trade-off because the simplicity of string could have better performance, and I'd be curious to test the impact once we do get rid of Emotion to see if it's worth it, but keyof React.JSX.IntrinsicElements means that we still validate that as="label" is a valid tag name.

This is improved in 85789d2 . I opted to just inline the type to solve both problems at once. Details in the extended commit description:

Improves a couple things:

Avoids a named type that references what it's used for (the "as" prop) rather than what it is

Avoids comments specifically referencing Emotion as the reason it's typed the way it is, as this is an objectively better, more accurate typing

manzoorwanijk · 2026-07-28T05:35:19Z

+	/**
+	 * Size of the underlying Modal. See `Modal`'s `size` prop.
+	 */
+	size?: ModalProps[ 'size' ];


This prop didn't land in the README for the component.

The short answer is that the component lacks a docs-manifest.json which would opt it into automatic documentation, and so its README is maintained manually. We could update it manually, but I'm also curious to dig into why it doesn't have a manifest 🙂

I tried adding the docs-manifest.json and it works (also brings other missing props like isBusy), but it causes a lot of unrelated changes to the README.md (changes formatting quite a bit) that I'd suggest we tackle separately. In the interim, da70077 adds the manual prop documentation.

Separate pull request for the auto-documentation: #80866

We could update it manually, but I'm also curious to dig into why it doesn't have a manifest 🙂

I set up the readme autogen system pretty late in the game, so a lot of them simply aren't migrated yet. Nothing more 😄

… components

Improves a couple things: - Avoids a named type that references what it's used for (the "as" prop) rather than what it is - Avoids comments specifically referencing Emotion as the reason it's typed the way it is, as this is an objectively better, more accurate typing

See: #80705 (comment) Since this can cascade to inner types like event handler props, we can do better than the loose `any` type as we know this will be an element.

manzoorwanijk

This looks good to me now. Thank you for working on this.

aduth · 2026-07-30T15:07:52Z

As a more visible data point, this looks to bring the typical runtime of "Type checking" in CI from about 2m40s to 1m45s (-35%).

Five examples before, from the latest 5 commits on trunk:

Two examples after, from the latest commit here and the one before my last force-push:

…ecifying `as` (#80705) * Components: Update polymorphism types to allow all attributes for all components * Components: Restore polymorphism for components passed as `as` * Sync components documentation * Update CHANGELOGs * Components: Inline PolymorphicAs typings Improves a couple things: - Avoids a named type that references what it's used for (the "as" prop) rather than what it is - Avoids comments specifically referencing Emotion as the reason it's typed the way it is, as this is an objectively better, more accurate typing * Components: Narrow generic type on polymorphic intrinsic types See: WordPress/gutenberg#80705 (comment) Since this can cascade to inner types like event handler props, we can do better than the loose `any` type as we know this will be an element. * Components: Document size prop Co-authored-by: aduth <aduth@git.wordpress.org> Co-authored-by: manzoorwanijk <manzoorwanijk@git.wordpress.org> Co-authored-by: mirka <0mirka00@git.wordpress.org> Co-authored-by: tyxla <tyxla@git.wordpress.org> Source: WordPress/gutenberg@b7376ac

aduth added the [Type] Build Tooling Issues or PRs related to build tooling label Jul 24, 2026

aduth requested review from a team and ajitbohra as code owners July 24, 2026 20:02

github-actions Bot added the [Package] Components /packages/components label Jul 24, 2026

aduth requested a review from manzoorwanijk July 24, 2026 20:03

This was referenced Jul 24, 2026

Components: Skip polymorphism prop typings on intersection #80364

Merged

Fix crashes when manipulating locked blocks #80509

Merged

aduth requested a review from Mamaduka July 24, 2026 20:04

aduth commented Jul 24, 2026

View reviewed changes

aduth marked this pull request as draft July 24, 2026 20:08

github-actions Bot added the [Package] Preferences /packages/preferences label Jul 24, 2026

aduth commented Jul 24, 2026

View reviewed changes

aduth marked this pull request as ready for review July 24, 2026 20:32

aduth requested a review from talldan as a code owner July 24, 2026 20:32

manzoorwanijk reviewed Jul 28, 2026

View reviewed changes

aduth added 7 commits July 29, 2026 16:14

Components: Update polymorphism types to allow all attributes for all…

cf4d603

… components

Components: Restore polymorphism for components passed as as

fa7f4ca

Sync components documentation

f1b72a0

Update CHANGELOGs

cf858f8

Components: Narrow generic type on polymorphic intrinsic types

5d3e989

See: #80705 (comment) Since this can cascade to inner types like event handler props, we can do better than the loose `any` type as we know this will be an element.

Components: Document size prop

da70077

aduth force-pushed the update/components-polymorphism-flat-attributes branch from 7e5d36a to da70077 Compare July 29, 2026 20:14

aduth mentioned this pull request Jul 29, 2026

Components: Opt-in ConfirmDialog for auto-documentation #80866

Merged

manzoorwanijk approved these changes Jul 30, 2026

View reviewed changes

aduth merged commit b7376ac into trunk Jul 30, 2026
65 of 71 checks passed

aduth deleted the update/components-polymorphism-flat-attributes branch July 30, 2026 15:09

github-actions Bot added this to the Gutenberg 23.8 milestone Jul 30, 2026

aduth mentioned this pull request Aug 4, 2026

Components: Deprecate Animate #80931

Merged

Uh oh!

Conversation

aduth commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What?

Why?

How?

Testing Instructions

Use of AI Tools

Uh oh!

github-actions Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aduth commented Jul 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Jul 24, 2026

Uh oh!

tyxla commented Jul 27, 2026

Uh oh!

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

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aduth Jul 29, 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!

manzoorwanijk left a comment

Choose a reason for hiding this comment

Uh oh!

aduth commented Jul 30, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

aduth commented Jul 24, 2026 •

edited

Loading

github-actions Bot commented Jul 24, 2026 •

edited

Loading

github-actions Bot commented Jul 24, 2026 •

edited

Loading

aduth commented Jul 24, 2026 •

edited

Loading

aduth Jul 29, 2026 •

edited

Loading