Docs/Media Manager

Media Manager

Upload, organize, and manage images and files in your project.

Media Manager

PhantomWP provides two ways to manage media: the Media Library modal for a visual gallery view, and the File Tree for file-based management. Both work with images in src/media/ which are automatically optimized by Astro.

Media Library

Click the Media icon in the header bar (image icon) to open the Media Library. This provides a visual grid of all your images.

Media Manager modal

Features

The Media Library shows:

  • Image thumbnails - Visual previews of all images in src/media/
  • Search bar - Filter images by filename
  • Upload area - Drag and drop or browse to upload
  • Image count - Shows total images in your library

Uploading Images

Drag and drop:

  1. Open the Media Library
  2. Drag image files from your computer
  3. Drop them in the upload area
  4. Files upload automatically with progress indicator

Browse files:

  1. Click the Browse Files button
  2. Select images from your computer
  3. Files upload to src/media/

Media Library upload

Supported formats: JPG, JPEG, PNG, GIF, WebP, SVG, AVIF

Using Images

Hover over any image to see action buttons:

Image hover actions

ActionDescription
Insert at CursorAdds import + Image component at your cursor position
Copy ImportCopies just the import statement to clipboard
Copy Full CodeCopies complete code with frontmatter
DeleteRemoves the image from your project

Insert at Cursor

This is the quickest way to add an image to your page:

  1. Position your cursor in a file where you want the image
  2. Open Media Library
  3. Hover over an image
  4. Click Insert at Cursor

The following code is inserted:

---
import { Image } from 'astro:assets';
import heroImage from '../media/hero.jpg';
---

<Image src={heroImage} alt="hero" />

Image Preview

Click any image to view it full-size. Click outside or press the X to close.

Image preview modal

Astro Optimization

Images stored in src/media/ get automatic optimization:

  • Format conversion - WebP/AVIF for supported browsers
  • Responsive sizes - Multiple sizes generated
  • Lazy loading - Images load as they come into view
  • Blur placeholders - Smooth loading experience

The info banner in the Media Library explains these benefits.

File Tree

The File Tree in the left panel also provides media management with more file-level control.

File Tree media folder

Project Structure

src/ media/ # Optimized images (recommended) components/ layouts/ pages/ public/ # Static files (favicon, etc.)

Two Media Locations

src/media/ - Images with Astro optimization (recommended)

  • Automatic format conversion
  • Responsive sizes
  • Lazy loading

public/ - Static files served as-is

  • Favicon and app icons
  • robots.txt
  • Open Graph default images
  • Files that must keep exact format

Uploading via File Tree

To src/media/:

  1. Right-click the src/media folder
  2. Select Upload Images
  3. Drag and drop or browse

To public/:

  1. Right-click the public folder
  2. Select Upload to Public
  3. Drag and drop or browse

Drag and Drop to Editor

Drag images directly from the File Tree into your code:

  1. Find the image in src/media/
  2. Drag it from the File Tree
  3. Drop it into your code editor
  4. The import and Image component code is inserted

Drag image to editor

Right-Click Menu

Right-click any image in src/media/ for quick actions:

File Tree context menu

ActionDescription
Insert at CursorAdds code at your cursor
Copy ImportCopies import statement
Copy Code SnippetCopies complete code
Copy PathCopies file path
DeleteRemoves the file

File Management

The File Tree also supports:

  • Create folders - Right-click > New Folder
  • Rename files - Right-click > Rename
  • Duplicate files - Right-click > Duplicate
  • Move files - Drag between folders
  • Search - Use the search bar to filter

Code Examples

Using the Image Component

---
import { Image } from 'astro:assets';
import heroImage from '../media/hero.jpg';
---

<Image src={heroImage} alt="Hero image" width={800} />

With Custom Dimensions

<Image 
  src={heroImage} 
  alt="Hero" 
  width={1200} 
  height={600}
  class="rounded-lg shadow-lg"
/>

In Markdown/MDX

import heroImage from '../media/hero.jpg';

<Image src={heroImage} alt="Hero" />

Best Practices

File Naming

Use descriptive, URL-friendly names:

  • Good: team-photo-2024.jpg, product-dashboard.png
  • Avoid: IMG_2847.jpg, Screenshot 2024-01-15.png

Folder Organization

Organize images by purpose:

src/media/ blog/ # Blog post images products/ # Product photos team/ # Team photos icons/ # Icon files

Image Sizing

  • Hero images: 1920px wide maximum
  • Content images: 800-1200px wide
  • Thumbnails: 400px wide
  • Icons: SVG preferred

Alt Text

Always add descriptive alt text:

  • Describe what's in the image
  • Keep it concise (125 characters or less)
  • Don't start with "Image of"

Troubleshooting

Upload Failed

If uploads fail:

  1. Check file size (large files may timeout)
  2. Verify file type is supported
  3. Ensure the Codespace is running
  4. Try refreshing the page

Image Not Showing

If an image doesn't appear:

  1. Verify the import path is correct
  2. Check the file exists in src/media/
  3. Make sure you're using the Image component
  4. Save and wait for hot reload

Thumbnails Not Loading

If Media Library thumbnails don't load:

  1. Wait a moment - previews load asynchronously
  2. Check WebSocket connection (green indicator in header)
  3. Refresh the Media Library

Next Steps

Previous
Component Library
Next
Font Manager