Managing Media & Folders

Use this page to learn how to organize, search, replace, and transform digital assets in your Dyrected media library. By the end of this guide, you will know how to create folder hierarchies, organize files, filter assets, replace images in-place without breaking relationships, and use URL transform presets.

The mental model

As your project grows, media libraries quickly accumulate hundreds or thousands of assets. Dyrected includes a built-in Digital Asset Management (DAM) system that organizes assets without altering their public delivery URLs or storage paths:

Folders are organizational taxonomy: A folder is metadata that groups files inside an upload collection. Moving a file between folders updates its organizational folderId but preserves its public CDN URL and database document ID.
In-place replacement protects relationships: When you update a product photo, banner, or document, replacing the asset updates the underlying file bytes while keeping the original document ID intact so referenced pages and records do not break.
Universal availability: The same folder hierarchy, search, and type filters available in the full Media Page are accessible inside document form fields via the Media Picker dialog.

Creating and navigating folders

Folders can be nested to any depth, allowing you to structure assets by department, campaign, year, or page section (for example: /Marketing/2026/Summer-Launch).

In the desktop admin interface, the left sidebar displays your complete folder tree:

Click + New Folder at the root or hover over an existing folder to add a subfolder.
Provide a name and optional color tag to help team members quickly scan categories.
Click any folder to filter the workspace view to only assets within that folder.
Use the All Media item at the top to view your complete library across all folders.

On mobile phones and tablet viewports, the folder tree transforms into a horizontal Folder Pill Carousel with breadcrumb navigation. Tap any pill to jump into a subfolder, or tap the breadcrumb trail to return to parent levels.

Organizing assets into folders

You can assign an asset to a folder when uploading or move existing assets at any time.

Moving a single asset

To move an individual file:

Hover over the asset card in grid view (or click the row in table view).
Click the folder icon or open the three-dots menu (···) and select Move to Folder....
Choose the target folder from the dropdown tree and confirm.

Moving multiple assets in batch

To organize multiple files at once:

Switch to table view or enable multi-selection in the Media Library dialog.
Select the checkbox for each asset you want to move.
Click Move Selected in the action bar, choose the destination folder, and click Move Assets.

Filtering and searching assets

The media filter bar helps you quickly find assets across large libraries:

Search by filename: Type any part of the original or stored filename in the search box.
MIME type chips: Filter instantly between All, Images (JPEG, PNG, WebP, SVG, GIF), Videos (MP4, WebM, YouTube, Vimeo), Audio (MP3, WAV), and Documents (PDF, DOCX, TXT).
Aspect ratio filter: Toggle between Square (1:1), Widescreen (16:9), and Original aspect ratio views to inspect thumbnails accurately.
View modes: Switch between the visual Grid View and the detailed Table View (which shows file size, MIME type, upload date, and quick action buttons).

Replacing assets in-place

When a design asset or document is updated, you usually want to replace the file without having to find and update every content document that references it.

Dyrected supports atomic in-place asset replacement:

Open the asset in the Media Inspector sidebar (or click Inspect Asset).
Click Replace File.
Choose the new file from your computer. Dyrected automatically restricts the file picker to matching MIME types (for example, only allowing images to replace an existing image).
The storage adapter replaces the stored file bytes and recalculates dimensions, aspect ratio, filesize, and BlurHash while preserving the original document ID.

All relations in other collections pointing to this asset immediately resolve to the new file with zero broken links.

Focal point and responsive crop

When displaying the same image across multiple aspect ratios (such as mobile portrait cards and desktop landscape banners), critical subject matter can be inadvertently cropped out.

In the Media Inspector, view the image preview.
Click anywhere on the image to set the Focal Point (represented by a central target indicator).
Dyrected saves the normalized coordinate (x and y between 0.0 and 1.0) on the asset document.
Your frontend components (such as DyrectedImage or custom CSS object-position: {x}% {y}%) use this coordinate to position crops centered around the subject.

Dynamic URL transformations

For projects utilizing dynamic image transformations, the Media Inspector provides one-click copy buttons for standard delivery presets:

Thumbnail: Copies a pre-configured 300px thumbnail transformation URL.
Banner: Copies a 1200px widescreen banner URL.
WebP: Copies the next-gen WebP format conversion URL.

These presets leverage your root image service configuration to serve optimized, device-appropriate assets to visitors globally.

Using folders in the SDK

You can also manage folders and query assets programmatically using the @dyrected/sdk client:

import { createClient } from "@dyrected/sdk";

const client = createClient({
  baseUrl: "https://cms.example.com",
  apiKey: process.env.DYRECTED_API_KEY,
});

// 1. Create a campaign folder
const folder = await client.createFolder("media", {
  name: "Summer 2026",
  color: "#3b82f6",
});

// 2. Fetch all media assets inside that folder
const { docs: summerAssets } = await client.collection("media").find({
  where: {
    folderId: { equals: folder.id },
  },
  sort: "-createdAt",
});

// 3. Replace an existing asset in-place
const updatedAsset = await client.replaceMedia(summerAssets[0].id, newFile);

Success check

You are ready to manage project assets when you can:

Create and navigate nested folders in desktop and mobile views.
Move assets between folders individually and in batch.
Replace an existing image in-place without altering its database ID.
Set focal points for responsive frontend cropping.