Media Library
FrankenCMS uses Spatie Media Library for powerful media management with automatic image processing, responsive images, and focal point cropping.
Uploading Media
Media can be uploaded in several ways:
- Featured Image: Upload directly on the post/page editor
- Content Images: Insert images via the rich editor
- Template Fields: Use
@frankenImagedirective
Featured Image tab showing the upload, the Generate with AI action, the focal point, and image details.
Image Processing
FrankenCMS generates these conversions for post and page images:
| Conversion | Size | Use Case |
|---|---|---|
thumb |
80×80 | Admin previews |
featured |
From Media settings | Featured image on the single post view |
listing |
From Media settings | Blog index and archive cards |
og |
1200×630 | Open Graph sharing image |
twitter / twitter-summary |
1200×675 / 600×600 | Large and summary Twitter cards |
The featured and listing aspect ratios, dimensions, and "Crop To Exact Dimensions"
options live under CMS Settings → Media. When cropping is on, crops are centered on the
image's focal point.
php artisan media-library:regenerate afterwards.
Displaying Images
Featured Images
@if($post->hasMedia('featured'))
@php($media = $post->getFirstMedia('featured'))
<img
src="{{ $media->getUrl('featured') }}"
alt="{{ $media->getCustomProperty('alt') }}"
style="{{ \FrankenCms\Support\FocalPoint::toCss($media->getCustomProperty('focal_point')) }}"
class="object-cover"
loading="lazy"
>
@endif
Responsive Images
@if($post->hasMedia('featured'))
{{ $post->getFirstMedia('featured')
->img('featured', ['class' => 'featured-image'])
->lazy() }}
@endif
Focal Point Cropping
A focal point keeps the important part of an image visible at every crop size:
- Upload a featured image, then click Update focal point below it
- Click the most important area of the image. The previews show how each crop will look
- Click Update and close, then save the post
The focal point picker previews each crop before you save.
Saving a new focal point regenerates the thumb, featured, and listing
conversions automatically. The value is stored on the media item as a percentage string such as
'50% 30%'. Use the FocalPoint helper to read it rather than parsing it yourself:
use FrankenCms\Support\FocalPoint;
$value = $media->getCustomProperty('focal_point');
FocalPoint::toCss($value); // 'object-position: 50% 30%;'
FocalPoint::normalize($value); // ['x' => 50, 'y' => 30]
The example theme's OG image templates honor the focal point too. With AI integration enabled, a Generate with AI action next to the upload can create the featured image for you.
Alt Text and Metadata
Always add alt text for accessibility and SEO:
// Get alt text
$alt = $media->getCustomProperty('alt');
// Get caption
$caption = $media->getCustomProperty('caption');
// Get all custom properties
$properties = $media->custom_properties;
Using Media in Template Fields
@frankenImage('banner.image', [
'label' => 'Hero Background',
'collection' => 'hero-images',
])
@
<div style="background-image: url('{{ frankenField('banner.image') }}')">
...
</div>
Storage Configuration
Configure the storage disk in your .env file:
# Use local public disk (default)
MEDIA_DISK=public
# Use S3 for production
MEDIA_DISK=s3