Mark useResponsiveValue as deprecated by siddharthkp · Pull Request #7760 · primer/react

siddharthkp · 2026-04-15T14:23:24Z

adr-018-responsive-values.md discourages the use of useResponsiveValue hook because it relies on matchMedia and needs to wait until client hydration to choose the right value.

Authors can use a hook called useResponsiveValue to support resolving the value of a prop based on the current viewport size. The implementation of this hook uses matchMedia which, unfortunately, has a downside: the value of a prop may shift when the component is server-side rendered. If the prop is used for styles or layout, then this will lead to a layout shift when the component hydrates and the viewport size is different than the fallback size on the server.

But, we still export this hook without any warnings. This came up in a conversation on slack.

Marking the hook as deprecated in the docs because we want people to use css media queries instead.

Bonus:

Add a reusable .github/skills/deprecations/SKILL.md guide for deprecating components and hooks.
Update contributor-docs/deprecating-components.md to document how deprecated status should be represented in component and hook docs metadata.

Rollout strategy

Patch release
Minor release
Major release; if selected, include a written rollout or migration plan
None; if selected, include a brief description as to why

Merge checklist

Added/updated tests
Added/updated documentation
Added/updated previews (Storybook)
Changes are SSR compatible
Tested in Chrome
Tested in Firefox
Tested in Safari
Tested in Edge
(GitHub staff only) Integration tests pass at github/github-ui (Learn more about how to run integration tests)

Agent-Logs-Url: https://github.com/primer/react/sessions/b0c0f40d-21cd-449f-8c67-2bd64b08b8b3 Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Agent-Logs-Url: https://github.com/primer/react/sessions/6f8c4762-fc70-4d71-ba62-cdade4e3de3a Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

changeset-bot · 2026-04-15T14:23:32Z

🦋 Changeset detected

Latest commit: d82618b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@primer/react	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

github-actions · 2026-04-15T14:23:59Z

⚠️ Action required

👋 Hi, this pull request contains changes to the source code that github/github-ui depends on. If you are GitHub staff, test these changes with github/github-ui using the integration workflow. Check the integration testing docs for step-by-step instructions. Or, apply the integration-tests: skipped manually label to skip these checks.

To publish a canary release for integration testing, apply the Canary Release label to this PR.

Copilot

Pull request overview

Marks the useResponsiveValue hook as deprecated in Primer React documentation and metadata tooling, aligning with ADR-018 guidance to avoid SSR hydration layout shifts.

Changes:

Add a JSDoc @deprecated annotation to useResponsiveValue with guidance to use getResponsiveAttributes + CSS media queries.
Introduce "status": "deprecated" for hooks in *.hookDocs.json, including schema/tooling support.
Add/extend contributor guidance for deprecations (new skill doc + update existing deprecation docs) and include a minor changeset.

Show a summary per file

File	Description
packages/react/src/hooks/useResponsiveValue.ts	Adds `@deprecated` JSDoc annotation to the hook.
packages/react/src/hooks/useResponsiveValue.hookDocs.json	Marks hook docs metadata as deprecated via `"status": "deprecated"`.
packages/react/script/hooks-json/hook.schema.json	Adds `status` field to the hook docs JSON schema.
packages/react/script/hooks-json/build.ts	Updates the local Hook type to include optional deprecated status.
contributor-docs/deprecating-components.md	Documents representing deprecated status in docs metadata for components/hooks.
.github/skills/deprecations/SKILL.md	Adds a reusable deprecations checklist/guide.
.changeset/cold-lions-listen.md	Adds a minor changeset announcing the deprecation.

Copilot's findings

Files reviewed: 7/7 changed files
Comments generated: 0

francinelucca · 2026-04-15T19:23:16Z

 - [ ] Adding a `@deprecated` annotation in the component's source code.
- [ ] Adding a `Deprecation` section to the documentation of the component with the link of the recommended component and provide a diff. See [deprecated ActionList docs](https://primer.style/react/deprecated/ActionList#deprecation) as an example.
+- [ ] Marking the component or hook docs metadata as deprecated with `"status": "deprecated"` in the relevant `*.docs.json` or `*.hookDocs.json` file.
+- [ ] If the component has a docs page, adding a `Deprecation` section to the documentation with the link of the recommended component and provide a diff. See [deprecated ActionList docs](https://primer.style/react/deprecated/ActionList#deprecation) as an example.


this link does not exist?

My bad, that link was already there. Replaced with a link for a recent deprecated component

francinelucca · 2026-04-15T19:24:27Z

+    "status": {
+      "type": "string",
+      "enum": ["deprecated"],
+      "description": "The status of the hook."
+    },


only valid value is deprecated? 🤔

Yes... because there was no status field so far.

Made it ["ready", "deprecated"] so it doesn't look weird

primer-integration · 2026-04-16T07:56:23Z

👋 Hi from github/github-ui! Your integration PR is ready: https://github.com/github/github-ui/pull/18723

primer-integration · 2026-04-16T08:05:10Z

Integration test results from github/github-ui:

CI Passed
VRT Passed
Projects Passed

All checks passed!

Copilot AI and others added 2 commits April 15, 2026 12:59

Deprecate useResponsiveValue hook

6ee63b9

Agent-Logs-Url: https://github.com/primer/react/sessions/b0c0f40d-21cd-449f-8c67-2bd64b08b8b3 Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

Add deprecation docs metadata guidance

0d0d091

Agent-Logs-Url: https://github.com/primer/react/sessions/6f8c4762-fc70-4d71-ba62-cdade4e3de3a Co-authored-by: siddharthkp <1863771+siddharthkp@users.noreply.github.com>

github-actions bot added the staff Author is a staff member label Apr 15, 2026

github-actions bot added the integration-tests: recommended This change needs to be tested for breaking changes. See https://arc.net/l/quote/tdmpakpm label Apr 15, 2026

siddharthkp marked this pull request as ready for review April 15, 2026 14:25

siddharthkp requested a review from a team as a code owner April 15, 2026 14:25

siddharthkp requested review from Copilot and francinelucca April 15, 2026 14:25

Copilot started reviewing on behalf of siddharthkp April 15, 2026 14:26 View session

Copilot AI reviewed Apr 15, 2026

View reviewed changes

siddharthkp deployed to github-pages April 15, 2026 14:33 — with GitHub Actions View deployment

github-actions bot temporarily deployed to storybook-preview-7760 April 15, 2026 14:33 Inactive

siddharthkp added the Canary Release Apply this label when you want CI to create a canary release of the current PR label Apr 15, 2026

francinelucca requested changes Apr 15, 2026

View reviewed changes

Add 'ready' status option to hook schema

d82618b

siddharthkp requested a review from francinelucca April 15, 2026 21:14

siddharthkp deployed to github-pages April 15, 2026 21:26 — with GitHub Actions View deployment

github-actions bot deployed to storybook-preview-7760 April 15, 2026 21:27 View deployment

francinelucca approved these changes Apr 15, 2026

View reviewed changes

siddharthkp added this pull request to the merge queue Apr 16, 2026

Merged via the queue into main with commit b2e0efd Apr 16, 2026
53 checks passed

siddharthkp deleted the copilot/mark-useresponsivevalue-deprecated branch April 16, 2026 08:18

primer bot mentioned this pull request Apr 15, 2026

Release tracking #7761

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mark useResponsiveValue as deprecated#7760

Mark useResponsiveValue as deprecated#7760
siddharthkp merged 3 commits intomainfrom
copilot/mark-useresponsivevalue-deprecated

siddharthkp commented Apr 15, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Apr 15, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

francinelucca Apr 15, 2026

Uh oh!

siddharthkp Apr 15, 2026

Uh oh!

francinelucca Apr 15, 2026

Uh oh!

siddharthkp Apr 15, 2026

Uh oh!

primer-integration bot commented Apr 16, 2026

Uh oh!

primer-integration bot commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

siddharthkp commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Rollout strategy

Merge checklist

Uh oh!

changeset-bot bot commented Apr 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions bot commented Apr 15, 2026

⚠️ Action required

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

francinelucca Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

siddharthkp Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

francinelucca Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

siddharthkp Apr 15, 2026

Choose a reason for hiding this comment

Uh oh!

primer-integration bot commented Apr 16, 2026

Uh oh!

primer-integration bot commented Apr 16, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

siddharthkp commented Apr 15, 2026 •

edited

Loading

changeset-bot bot commented Apr 15, 2026 •

edited

Loading