Content

Media library

Upload, find and replace images, documents and fonts without changing existing published uses.

GroCMS 0.1.0 · Reviewed 15 September 2026

Download this guide

What the library stores

The Media library stores images, PDF documents and WOFF2 font files used by content and site design. Uploading a file creates a reusable asset with its own identity. It does not automatically put that asset onto a page or make it publicly downloadable. A content entry, composition or design resource must refer to the chosen asset version.

Administrators, editors, authors and designers have media capability; contributors do not. Administrators and editors can browse site media. Other permitted roles can browse their own assets and eligible publicly used assets. Only administrators and designers can upload WOFF2 fonts. Seeing a public asset does not automatically grant the right to replace its metadata.

Sources: Media library screen; Media storage and access rules; Resource permission policy.

Upload and find files

  1. Open Media library and choose Upload files.
  2. Choose one or more JPEG, PNG, WebP, PDF or WOFF2 files. Keep each file within the stated 15 MB limit; font uploads also require the appropriate role.
  3. Choose Add to library and wait for the result. If one file fails, inspect the refreshed library before retrying: earlier files in that batch may already have uploaded.
  4. Search by the asset's name and use the previous/next media page controls for older uploads. The library shows 50 results per page.
  5. Open an asset card to inspect its type, size, upload date, dimensions when available, Asset URL and Media ID.

Accepted images are normalised to WebP, rotated according to their image metadata and reduced to fit within 2,400 pixels without enlargement. Very large pixel dimensions or malformed image data can be rejected even when the file size is small. Keep an original outside the CMS when you need its original format or full resolution for print.

Copy URL gives you the delivery address, while Copy ID gives the internal asset reference used by integrations. Ordinary authors should select assets through Featured image, Image or font controls rather than pasting identifiers into text. PDF delivery is a download, not an embedded document viewer.

Sources: Media library screen; Media storage and access rules.

Edit a name, alternative text or file

  1. Open the asset and choose Edit / replace.
  2. Set Name to a useful library label. Alternative text describes meaningful image content for people who cannot see it.
  3. Leave Replacement file (optional) empty to keep the exact file bytes with the new metadata, or choose a replacement file.
  4. Choose Create new version. The result has a different Media ID, even when only the name or alternative text changed.
  5. Open each entry that should use the replacement, select the new asset, save and publish that entry when ready.

This deliberate extra selection protects existing work. Changing the alternative text of a photograph does not silently rewrite a published article or its history. Existing references continue to use the previous version's name, alternative text and bytes. The new version starts private and is not an automatic replacement everywhere the old file appears.

For example, replace a poster containing last year's date with the corrected poster. The old event page remains reproducible until you choose the new poster in the event's draft and publish it. If only the asset name needs tidying, the new version still needs to be selected where you want that new metadata to apply.

Sources: Media replacement dialog; Media storage and access rules; Authority and media integration tests.

Understand private and public delivery

Anonymous visitors can fetch an asset only while an eligible current public publication refers to it. Your authenticated access may let you preview a private upload, so a URL working in your own browser does not prove that it works for visitors. A newly created replacement will fail for anonymous visitors until a public use selects its new ID.

If a file is used by both a public and a private entry, the public use makes that exact file available publicly. Marking one referencing entry private does not conceal bytes still used elsewhere publicly. Withdrawing the last public use removes anonymous delivery for subsequent requests; it cannot recall a file someone already downloaded.

Sources: Media storage and access rules; Authority and media integration tests.

Selection and upload problems

An image picker filters to image files and a font picker filters to fonts before pagination. A PDF therefore will not appear as a valid featured image. Previously selected older assets are resolved by their exact ID even when they are outside the visible result page. Search another page before assuming an older upload has disappeared.

Replacement is allowed for the owner or an administrator/editor with site access. A designer editing someone else's private upload may receive an access error. Unsupported SVG, HTML and other active file formats are outside the upload allowlist. If copying fails because the browser blocks clipboard access, select the displayed ID or URL and copy it manually.

Sources: Media library screen; Media replacement dialog; Media storage and access rules; Editor browser journeys.

  • PostsWrite and organise stories, understand authorship and choose publication or review.
  • PagesCreate permanent website pages, manage their addresses and publish changes deliberately.
  • Visual editorArrange the available components, connect content, and understand the limits of the canvas.
  • Brand & themeSet the website's identity, colors, fonts, and logo, with clear limits on what these controls change.
  • API keys & content exportConnect an application with scoped credentials and understand exactly what a workspace export contains.
  • Backup and restoreProtect database and media together, rehearse recovery and resume schedules deliberately.