[v4] UI component pages suggest deep imports inside the Admin Panel

Open
#19,510 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

@josecrc is already working on this.

Since Nov 11, 2026.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
25/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
react, typescript
Domain
documentation

Research direction

Review the 13 pages listed under docs/ui-components/ and compare their import guidance with docs/troubleshooting/troubleshooting.mdx and the note in packages/ui/bundle.js. Update the guidance to explain that deep imports are for use outside the Admin Panel and link to Troubleshooting. Done when all 13 pages clearly distinguish the supported import contexts; pull request #19528 is already open for this issue.

Written by the indexing model from the issue text.

Description

Bug created-by: Contributor Payload-OSS

Documentation Issue

13 pages under docs/ui-components/ show the root import "Inside a Payload Admin Panel Custom Component" and then add "You can also import the component directly:" with a deep path, e.g. button.mdx:

(live page on docs https://payloadcms.com/docs/beta/ui-components/button)

import { Button } from '@payloadcms/ui/elements/Button'

Read in that order, it sounds like an equivalent option in the admin. But Troubleshooting says deep imports should only be used outside the Admin Panel, and packages/ui/bundle.js notes that the deep entries "hold their own copies of providers and contexts". In practice, a client component in the admin that imports Popup from @payloadcms/ui/elements/Popup throws Cannot destructure property 'config' of … as it is undefined on its first render, because its useConfig reads a context no provider supplies.

Pages: animate-height, banner, button, card, collapsible, copy-to-clipboard, error-pill, gutter, link, pill-selector, pill, react-select, shimmer-effect.

Suggestion: change the line to something like "Outside the Admin Panel (e.g. in your frontend), import the component directly to keep your bundle small", and link to the Troubleshooting section.

Dominant language
TypeScript
Stars
45.8k
Forks
4.4k
Avg merge
2d 16h
Merged PRs (30d)
251

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from payloadcms/payload

All issues in payloadcms/payload

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.