Skip to content

docs(react): document the _tagIds id-tagging option - #452

Open
moss-bryophyta wants to merge 1 commit into
mainfrom
docs/next-tagids-option
Open

docs(react): document the _tagIds id-tagging option#452
moss-bryophyta wants to merge 1 commit into
mainfrom
docs/next-tagids-option

Conversation

@moss-bryophyta

Copy link
Copy Markdown
Contributor

What

Documents the opt-in _tagIds option in the Next.js withGTConfig reference. It shipped in gt-next@11.1.6 (published 2026-08-10) via gt#2017 and was not documented anywhere in the docs.

Why it needs care

_tagIds injects markup, so the docs have to be precise about when. I wrote this against the implementation in renderPreparedT.shared.ts rather than the changelog, which surfaced two cases the changelog summary does not spell out:

  • Component roots also get wrapped. The wrapper check is typeof rendered.type === 'string', so it matches host elements only. A <T> wrapping a component root takes a span just like bare text and fragments. The changelog mentions only "bare text or a fragment."
  • Output that renders nothing is deliberately left untouchednull, undefined, booleans, '', arrays whose entries all render nothing, and empty fragments. rendersNothing() exists specifically so an empty <span data-_gt-hash> never appears and changes :empty/child structure. 0 and NaN do render and are tagged normally.

Also documented: the literal-true requirement (isIdTaggingEnabled() is === true, and there is a test asserting truthy-but-malformed values stay off), no effect on gt()/useGT() strings, and the React Native skip.

Verification

  • All five validators pass. The reference-link validator caught a bare `<T>` in the options table on the first run; fixed by linking it to /docs/react/reference/components/t.
  • Confirmed gt-next@11.1.6 is the current published version on npm.
  • Confirmed no other doc page or open PR covers _tagIds.

Reviewers

@logflash authored the feature, so flagging the component-root and renders-nothing cases for confirmation — I derived them from reading the source, not from the changelog.

Adds the opt-in `_tagIds` option to the Next.js `withGTConfig` reference,
shipped in gt-next@11.1.6 (gt#2017) and previously undocumented.

Covers the exact span-injection behavior from the implementation:
host elements are annotated in place, bare text/fragments/component roots
get a layout-neutral display:contents span, and output that renders
nothing is left untouched.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant