Media Library

The Media Library stores reusable images, documents, video, and audio. Editors can upload files once, select them from content fields and Portable Text, and see which content entries refer to a local media item.

Open the Media Library

Select Media in the admin sidebar. The Main library contains folders and files that have not been placed in a folder. Select a folder to browse its files, or switch between grid and list views.

If the site has external media providers, each provider appears as another source. Provider capabilities vary: a source may support browsing and selecting but not folders, local image editing, or deletion.

Upload files

Upload from the library

1. Select Media, then Upload Files.

2. Select Browse files and choose one or more files. You can also drag files onto the upload area or the Media Library.

3. Leave the dialog open while the files upload. Each row reports Queued, Uploading, Complete, or Upload failed.

4. For a failed file, select its retry action. You can cancel unfinished uploads, remove a failed row, or clear completed rows without affecting files that already finished.

5. Select Done when the queue has no unfinished uploads.

Uploads begin as soon as files are added. New local files enter the Main library, even when another folder was open before the upload.

Upload while editing content

Image, file, gallery, and Portable Text image fields use a media picker. Open the field, select Upload files, and choose or drop files. A completed upload becomes part of the current selection; failed uploads stay visible so you can retry or remove them.

For a gallery, review Selected media and use the move controls to set the order before selecting Add images. For a single image or file, select Select or Insert image after the upload finishes.

Accepted files and size limit

The local Media Library accepts these file groups by default:

• PNG, JPEG, GIF, WebP, and AVIF images;
• common video formats such as MP4, WebM, and QuickTime video;
• common audio formats such as MP3, WAV, and Ogg audio; and
• PDF documents.

SVG is excluded from the default upload list because SVG files can contain active content. An image or file field can define its own list of accepted file types when the content model needs a narrower selection or another format. EmDash identifies each file by its media type, a label such as image/png or application/pdf, and checks the field’s list again when content is saved. Changing the browser’s file chooser does not bypass that server check.

The default maximum is 50 MB per file. Site developers can change it with maxUploadSize. A provider may impose an additional format or size limit and will report that failure in the upload row.

Find and organize files

Search matches partial filenames. The type filter limits results to images, documents, video, or audio. A filename search covers the whole local library, even while a folder is open; browsing a folder without a search shows only the files assigned to that folder.

Editors can select Add new folder in the Main library. Move a local file by dragging its card or row onto a visible folder, or open the file, change Location, and select Save. Use Main library as the location to remove a file from its current folder.

Authors can move local files they uploaded. Editors can move any local file. External-provider items cannot be assigned to Media Library folders.

Deleting a folder moves its files back to the Main library. It does not delete the files, change their URLs, or remove their content references.

Select media for content

Portable Text images

Place the cursor in a Portable Text field, open the block menu, and select Image. Choose or upload an image, then select Insert image. Select the image block afterward to add alt text, a caption, display dimensions, and alignment.

Image and file fields

Select the field action, such as Select image or Select file, then choose an item and confirm the selection. A field’s MIME-type rules limit which library items and media sources appear.

The blog template’s featured_image field stores the selected media value with the post. Saving the entry saves that reference to the draft; publishing makes it available to public content queries.

Gallery fields

Select one or more images, arrange them under Selected media, and confirm. A gallery keeps its own order and per-image alt text and caption, even when several positions refer to Media Library items.

Edit an image used in content

A selected local image offers actions with different scopes:

• Replace chooses a different Media Library item for this field, block, or gallery position. Other entries that use the original item do not change.
• Edit asset opens the underlying Media Library item. Metadata changes and destructive image changes may affect other uses of that item.
• Remove clears this content reference. The Media Library item remains available.

When Edit asset creates a cropped copy, the picker selects the new copy for the current use. Portable Text and gallery images keep that use’s alt text, caption, layout, and position. When Edit asset replaces the original, the media ID stays the same, so every use of that item receives the changed image.

External-provider images and file fields offer Replace and Remove but do not open the local asset editor.

Replace a local image

Replace image uploads new bytes behind an existing Media Library item. Use it when every place that refers to the item should show a new version of the image.

The action is available for ready JPEG, PNG, and WebP items. Authors can replace images they uploaded; editors can replace any local image.

1. Open Media and select the local image.

2. Stay on Details and select Replace image.

3. Choose a non-empty image in the same format. A JPEG must be replaced by a JPEG, for example, but the new image may have different dimensions or a different aspect ratio.

4. Read the confirmation, then select Replace image.

EmDash keeps the media ID, filename, URL, alt text, caption, and folder. Existing content references therefore continue to work and show the replacement. The replacement clears the saved focal point because its coordinates may not describe the new image.

Caution

Replacing an image cannot be undone. EmDash does not retain the previous file. The URL remains the same, so a browser or content delivery network may briefly serve cached bytes from the earlier image.

Use Replace in the content editor instead when only one field or image block should change.

Set a focal point

A focal point marks the part of an image that should remain visible when a layout crops the image to fill a square, landscape, portrait, or other fixed shape.

1. Open a local image in Media, or select Edit asset from an image used in content.

2. Select Edit image, then Focal point.

3. Select or drag the marker onto the important part of the image. The Arrow keys move a focused marker without a pointer.

4. Check the portrait, square, and landscape previews, then select Save.

Select Reset to remove the custom point. When you choose an image for a field or gallery, EmDash copies the asset’s current focal point into that content value. Content that already uses the image keeps its stored point until you select the image again. Opening Edit asset from a content field updates that current use with the point you save.

Crop a local image

Cropping is available for ready JPEG, PNG, and WebP images stored by EmDash. External-provider images cannot be cropped in the local asset editor.

1. Open the image and select Edit image, then Crop.

2. Choose Original, Freeform, Square, 4:3, 3:2, or 16:9. A fixed ratio keeps its shape while you resize it. Freeform lets the width and height change independently.

3. Move and resize the crop frame. You can drag with a pointer or focus the frame and its handles and use the Arrow keys. Hold Shift with an Arrow key for a larger step.

4. Choose how to save the result:

   • Create cropped copy creates a new Media Library item and leaves the source unchanged.
   • Replace original keeps the media ID and changes the image everywhere it is used.

Replace original is available only with the Original aspect ratio. Use Create cropped copy for Freeform and the other ratios. A cropped copy stays in the same folder as its source and receives a unique filename.

Caution

Replace original cannot be undone. EmDash keeps neither the uncropped bytes nor a crop history. Existing entries keep the same media reference and are not rewritten or republished. Because the URL stays the same, caches may briefly show the uncropped image.

Cropping an animated WebP creates a still WebP. The cropped result does not retain the animation.

See where a file is used

Open a local file and select Used in to list content entries that refer to it. Each result names the collection and fields that contain the reference and can open the entry for editing. Trashed entries are identified in the list.

Media usage tracking must be active before this list can be complete. An administrator turns it on once for the site:

1. Finish current content edits. Pause scripts, imports, and other tools that write to content, then wait for their in-progress writes to finish.

2. Open Settings, then Media usage tracking, select Enable tracking, and acknowledge the preparation steps.

3. Keep editing paused while the status says Setting up. EmDash prepares each collection so future saves can update its usage records. It temporarily refuses content, schema, revision, import, and MCP writes so no change can occur between that preparation and tracking becoming active.

4. When the status changes to Indexing existing content, normal editing can resume. Keep the settings page open while EmDash scans existing entries.

5. Wait for Ready. If you leave the page, return later and the scan continues from its saved progress.

Once enabled, media usage tracking cannot be turned off. New content changes are tracked after capture becomes active; the background scan adds references from entries that already existed.

Caution

Used in checks supported references stored in EmDash content. It does not inspect custom source code, generated HTML, another database, or an external site. An empty or incomplete list does not prove that deleting the file is safe.

If the Used in view reports that indexing is running, stale, partial, or failed, treat its results as incomplete. An administrator can return to Media usage tracking for the current status and recovery guidance.

Render an image in a template

Image fields return a media value rather than a plain URL. Render that value with Image from emdash/ui so local and provider-backed images use the appropriate URL, dimensions, focal point, responsive variants, and low-quality placeholder:

src/pages/posts/[slug].astro (excerpt)

---
import { getEmDashEntry } from "emdash";
import { Image } from "emdash/ui";

const { entry: post, error } = await getEmDashEntry("posts", Astro.params.slug);
if (error) return new Response("Unable to load post", { status: 500 });
if (!post) return Astro.redirect("/404");
---

{post.data.featured_image && (
  <Image image={post.data.featured_image} width={1200} height={675} priority />
)}

Use priority only for the main image visible at the top of the page. It requests eager loading and gives the browser a high fetch-priority hint. Other images should retain the component’s lazy-loading default.

If the field has a dark-mode counterpart, Image renders both sources and selects one from the visitor’s color scheme. See Dark mode images for the field and template setup.

The template receives the media metadata stored with the content reference without another Media Library query. If a custom integration requires the provider’s latest metadata, request that item explicitly and avoid one provider lookup per image on a collection page. The field type reference describes stored file and image values.

Configure storage and providers

The local library stores files through the site’s configured storage adapter. Node.js sites can use local disk or S3-compatible storage; Cloudflare sites commonly use an R2 binding. The adapter decides where bytes are stored, while the Media Library keeps the same authoring workflow. See Media storage for configuration and production persistence requirements.

Cloudflare Images and Cloudflare Stream can be registered as external media providers. They appear as sources in the picker, and Image understands provider-backed image values. Provider items remain managed by that service, so local folders, focal points, cropping, and replacement are unavailable for those items in the EmDash asset editor.

Delete media safely

Open a file in the Media Library, select Delete, and confirm the permanent deletion. Authors can delete local files they uploaded; editors can delete any local file. A provider item is deleted from its provider only when that source exposes deletion and the current user has permission.

Caution

Media deletion has no Trash and cannot be undone. It does not remove or rewrite content references. Review Used in, search any custom templates or data stores that may contain the URL, and update those uses first. Remaining references may render a broken image or file link.

For automated uploads and media management, see the media endpoint reference or the CLI media commands. Continue with Working with Content to publish entries that use the selected media.