Why the Picker Doesn’t Show on Every Image Field
If you’ve opened the Puck editor, added an “Image” block, and found yourself pasting a URL by hand instead of picking from a library, this page is why, confirmed directly from this project’s own code, not the plugin’s general capabilities.
The media library is real and working. Confirmed both from code and from a live test in the editor: the “Media Figure” component opens a real picker, showing saved assets with alt text, caption, credit, and byline metadata already attached. If you’re not seeing that, you’re almost certainly in the wrong component.
Is there a standalone Media Library screen, separate from Puck?
No, confirmed, not just unobserved. Unlike WordPress’s Media → Library screen
(browsable independent of any post), P1’s media library has exactly one UI surface:
the picker modal that opens when you click a rich-mode (p1-media) field inside a
Puck component. There is no separate section in the content.pantheon.io dashboard for
browsing or managing assets outside that context, and no way to see the whole
library at once, independent of a specific field’s picker (see
Bulk Management & a Library View for what that
gap means in practice and the feature that would close it).
This is confirmed two ways, not just “we didn’t find it while looking”:
@pantheon-systems/css-client, the SDK the content.pantheon.io dashboard itself is built on, exposes endpoints for branches, checkpoints, documents, merges, templates, versions, sites, and presence. No media or asset endpoint anywhere. The dashboard backend literally has no concept of media to build a screen around.- Pantheon’s own dev guide describes
p1-mediaas, specifically, “a Puck plugin”. Its picker is implemented as a Puck field-type override (overrides.fieldTypes), which by construction only renders inside the Puck canvas, in response to clicking a field. There’s no separate route or dashboard page it also renders on.
Worth raising with Pantheon directly if a WordPress-style standalone library screen (browse/upload/manage assets independent of any page) matters for your editorial workflow. Nothing found suggests one is planned, but we haven’t seen a roadmap.
Confirmed: the plugin is active in this project’s editor
app/p1/(editor)/[[...p1]]/editor-client.tsx calls createMediaPlugin({}) and passes
it into additionalPlugins for useP1Editor. The library, the picker, cropping, and
CDN delivery are all live and working in this project today, verified by testing the
Media Figure component directly in the editor: its “Choose from Library” button opens
a real picker with a saved asset already carrying alt text, caption, credit, and
byline fields.
Confirmed: two competing image components, only one uses it
puck.config.tsx registers both of these in the same “Media” sidebar category (see
Components Reference → Media):
| Component | Field | Picker? |
|---|---|---|
Image (image-block.tsx) | src, plain text | No |
Media Figure (media-figure-block.tsx) | built via createMediaFigureBlock, a real p1-media rich field | Yes |
The Image block’s field is literally named src. Confirmed directly from the
plugin’s compiled source, the patterns that trigger the picker on a basic-mode text
field are:
/^image(?:Url)?$/ /^logo(?:Url)?$/ /^media(?:Url)?$/ /^icon(?:Url)?$/
/^thumbnail(?:Url)?$/ /ImageUrl$/ /LogoUrl$/src matches none of them. It’s not a bug in the plugin: the field name simply isn’t
one of the recognized patterns, so the plugin correctly leaves it alone as a plain
text field. The picker was never going to appear on this specific field, regardless
of whether the plugin is active elsewhere in the same editor.
This also explains the alt-text-retyping problem
Directly relevant if you’ve noticed the same image needing its alt text retyped every time you reuse it. See Requirements: WebP Delivery & Alt Text for the full picture.
The Image block’s alt field is a fully independent piece of text per component
instance; there’s no asset behind it to remember anything. Media Figure is
different: rich-mode values carry “a snapshot of the metadata defaults copied at edit
time” (confirmed from the MediaValue type’s own doc comment, and now confirmed live
in the editor too), meaning if an asset’s alt text is filled in once in the
library, picking that same asset again in a different Media Figure elsewhere on the
site starts from that saved value instead of blank, editable per-instance from
there. That efficiency only exists on the rich-mode path; the plain Image block was
never going to have it.
What to actually do about it
- Use Media Figure, not Image, for any real content photo. It’s already registered and working, no new build required.
- Fill in alt text (and other metadata) once, in the library, at upload time, not per-placement, so it’s available as a starting snapshot everywhere that asset gets reused.
- Consider relabeling or removing the Image block so this isn’t a trap for the next editor or agent who reaches for “Image” first because it’s the more obviously-named option. At minimum, rename its sidebar label to something like “Image (external URL)” to make the distinction visible in the editor itself, not just in this documentation.
If your actual need is genuinely “paste an arbitrary external URL” (a third-party badge, a logo hosted elsewhere), that’s what the Image block is legitimately for. The gap here is that nothing in the editor UI itself tells you which one to use when, so both an editor and an AI agent are equally likely to guess wrong.