Guide to managing media
Learn how to upload, organize, crop, and reuse media in ApostropheCMS — including how image optimization, focal points, and DAM integrations work for content editors.
-
- Beginner
- 6 min read
- Content Management
- Content Creation
- Last Updated August 4, 2026
Managing Media in ApostropheCMS
Apostrophe includes a built-in Media Library that handles image storage, organization, and optimization without requiring a separate digital asset management (DAM) tool. This guide covers how to upload, organize, edit, and reuse media — and explains a few things the platform handles automatically so you know what to expect.
The Media Library: your built-in DAM
The Media Library is Apostrophe's central repository for images and files. Any image you upload through a content area or image field is automatically stored here and becomes available for reuse anywhere on the site.
The library is accessible from the admin bar at the top of the page. It's split into two sections:
- Images — for visual media (JPG, PNG, GIF, SVG, WebP)
- Files — for documents and other non-image attachments (PDF, Word, etc.)
Upload directly to the library
Open the Media Library from the admin bar and use the upload button to add files without placing them on a page yet. This is useful for preparing assets in advance.
Upload while editing content:
When you add an image widget to a page or click into an image field, you'll see the image picker. From there you can upload a new file or select one already in the library.
Apostrophe accepts JPG, PNG, GIF, WebP, and SVG. SVG files have one limitation: they cannot be cropped (more on that below).
How image optimization works
When you upload an image, Apostrophe automatically generates multiple size variants behind the scenes. You don't need to prepare or export different sizes before uploading: upload a high-resolution original and the platform handles the rest.
These variants are used to serve the right size for the right context, reducing page load times without any manual work on your part.
Responsive images and focal points
Because your images appear across many screen sizes and layouts, Apostrophe includes a focal point tool to ensure the most important part of an image stays visible when it's cropped or resized by CSS.
When selecting or editing an image, you'll see an option to set a focal point. Click on the subject of the image (a face, product, or other key visual element) and Apostrophe will bias the display toward keeping that point visible, regardless of device or crop ratio.
This is especially important when:
- A landscape image is displayed in a square or portrait context
- Your layout shows images at different ratios on mobile vs. desktop
- You want to avoid an automatic crop that cuts off a person's head or a product's key detail
The focal point is stored per image-widget placement, not on the image itself — so the same source image can have different focal points in different contexts.
Cropping and editing images
Apostrophe's image editing tools are non-destructive. When you crop an image, the original is preserved in the library. The crop only applies to that specific placement, which means:
- The same image can be used in different aspect ratios in different places on the site
- You never lose the original by editing
- SVG files cannot be cropped (this is a technical limitation of the format)
To crop an image after selecting it
- Select the image in an image widget or field.
- Use the crop tool that appears in the image editing interface.
- Adjust the crop region; if your developer has set a fixed aspect ratio for that area, the crop tool will enforce it automatically.
- Save. The crop applies only to this placement.
Organizing your library: tags and search
The primary organizational tool in the Media Library is tags. Tags are freeform labels you apply to images to make them easier to find later.
Filtering and search
The library supports filtering by:
- Tag
- File type (JPG, PNG, etc.)
- Orientation (landscape, portrait, square)
- Source (useful if external media sources like Unsplash are integrated)
Use the search bar to find images by title or alt text. Keeping image titles and alt text meaningful pays off here: "hero-homepage-2024.jpg" is far easier to locate than "IMG_4823.jpg".
Best practices for organization
- Rename images to something descriptive before or after uploading
- Apply tags consistently — agree on a tagging taxonomy with your team (e.g., by campaign, content type, product line, or locale)
- Add alt text to every image at upload time
Batch operations
For teams managing large media collections, the library supports batch operations so you can work across multiple images at once.
To perform a batch action
- Open the Media Library
- Select multiple images using the checkboxes
- Choose an action from the batch operations menu
Available batch actions
- Add tags to multiple images at once
- Remove tags from multiple images
- Archive multiple images
- Localize multiple images
You can also create new tags on the fly during a batch tagging operation, so you don't need to pre-configure your taxonomy before you start organizing.
Image linking
As of recent versions, images in both the image widget and rich text editor support adding links to external URLs, internal pages, or piece show pages. This makes it possible to use an image as a visual call-to-action without needing a separate button widget.
To add a link to an image widget, look for the link option in the image editing interface after selecting your image.
Storage and hosting
By default, Apostrophe stores uploaded media on the local file system. For production sites, most teams configure cloud storage (Amazon S3 or equivalent) so that media is served efficiently and persists independently of server deployments.
As an editor, you won't see or interact with this directly — uploads and image URLs work the same regardless of where files are stored. If images unexpectedly break after a deployment or environment change, this is worth flagging to your developer.
Quick reference: what editors control vs. what developers configure
Area | Editor controls | Developer configures |
|---|---|---|
Image upload | Upload, title, alt text, tags | Allowed file types, storage location |
Cropping | Crop placement, focal point | Aspect ratio constraints, minimum sizes |
Optimization | Nothing needed — automatic | Variant sizes, |
Organization | Tags, search, filtering | Tag taxonomies, custom filters |
Batch operations | Tagging, deletion | Custom batch actions |