Deprecating components and hooks in Primer React

Use this skill when a task involves marking a public Primer React API as deprecated.

What to update

Source code

• Add a JSDoc @deprecated annotation to the exported component, hook, prop, or type following existing patterns nearby.
• Keep runtime behavior unchanged unless the task explicitly requires more than deprecation signaling.

Docs metadata

• For components, mark the relevant *.docs.json file with "status": "deprecated".
• For hooks, mark the relevant *.hookDocs.json file with "status": "deprecated".
• If schema or build tooling does not yet support the docs metadata you need, update the corresponding schema/build files in packages/react/script/*-json/.

Documentation content

• If the deprecated component has a docs page or JSON-backed docs content that supports deprecation guidance, add or update the deprecation guidance and recommended alternative.
• Follow contributor-docs/deprecating-components.md.

Versioning

• Add a changeset for public API deprecations.
• Use the versioning guidance in contributor-docs/versioning.md to choose the correct bump.

Validation

Prefer targeted validation first, then broader validation if needed:

• Format changed files with npx prettier --write <paths>
• Lint changed TypeScript files with npx eslint --fix <paths>
• Rebuild generated docs metadata when related schema or docs JSON changes:

npm run build:hooks.json -w @primer/react

npm run build:components.json -w @primer/react

• Run targeted tests for the affected API when available
• Run broader repository validation before finalizing if the change touches shared build tooling

Common files

• packages/react/src/**/*.docs.json
• packages/react/src/**/*.hookDocs.json
• packages/react/script/components-json/*
• packages/react/script/hooks-json/*
• contributor-docs/deprecating-components.md
• .changeset/*.md