Getting started
Image editor
The ImageEditor component is a form component that allows users to edit images directly in the browser. It can be used independently of the AdvancedFileUpload component in any Filament form:
use RalphJSmit\Filament\Upload\Filament\Forms\Components\ImageEditor;
ImageEditor::make('image_path')
->disk('s3')
->directory('images')Uneditable file message
When a file type cannot be edited, a message is displayed to the user. You can customize this message using the following methods:
use Filament\Support\Icons\Heroicon;
ImageEditor::make('image_path')
->uneditableFileMessageIcon(Heroicon::OutlinedExclamationTriangle)
->uneditableFileMessageTitle('This image cannot be edited')Configuring the editor globally
You can configure the image editor globally using the configureUsing() method in a service provider or in the bootUsing() method of a panel. This allows you to set default options for all ImageEditor instances in your application:
use RalphJSmit\Filament\Upload\Filament\Forms\Components\ImageEditor;
use RalphJSmit\Filament\Upload\Filament\Forms\Components\ImageEditor\Tab;
use RalphJSmit\Filament\Upload\Support\ImageEditor\CropPreset;
// In a service provider boot() method or panel bootUsing() callback:
ImageEditor::configureUsing(function (ImageEditor $editor) {
$editor
->tabs([Tab::Adjust, Tab::Watermark])
->cropPresets([
CropPreset::make('square', ratio: 1.0),
]);
});Any configuration set on an individual ImageEditor instance will override the global defaults for that property.
Tabs
By default, the image editor shows all available tabs. You can restrict which tabs are visible using the ->tabs() method:
use RalphJSmit\Filament\Upload\Filament\Forms\Components\ImageEditor\Tab;
ImageEditor::make('image_path')
->tabs([Tab::Adjust, Tab::Annotate, Tab::Watermark])The available tabs are: Tab::Adjust, Tab::Finetune, Tab::Filters, Tab::Watermark, Tab::Annotate, and Tab::Resize.
You can also set which tab and tool are selected when the editor opens:
use RalphJSmit\Filament\Upload\Filament\Forms\Components\ImageEditor\Tab;
use RalphJSmit\Filament\Upload\Filament\Forms\Components\ImageEditor\Tool;
ImageEditor::make('image_path')
->defaultTab(Tab::Annotate)
->defaultTool(Tool::Text)The available tools are: Tool::Crop, Tool::Rotate, Tool::Flip, Tool::Brightness, Tool::Contrast, Tool::HSV, Tool::Warmth, Tool::Blur, Tool::Text, Tool::Image, Tool::Rect, Tool::Ellipse, Tool::Polygon, Tool::Pen, Tool::Line, and Tool::Arrow.
Crop presets
You can add custom crop presets that appear in the crop tool dropdown:
use RalphJSmit\Filament\Upload\Support\ImageEditor\CropPreset;
ImageEditor::make('image_path')
->cropPresets([
CropPreset::make('classicTv', ratio: 4 / 3)->description('4:3'),
CropPreset::make('cinemascope', ratio: 21 / 9)->description('21:9'),
CropPreset::make('square', ratio: 1.0)->description('1:1'),
])You can also organize presets into folders with groups:
use RalphJSmit\Filament\Upload\Support\ImageEditor\CropPreset;
use RalphJSmit\Filament\Upload\Support\ImageEditor\CropPresetFolder;
use RalphJSmit\Filament\Upload\Support\ImageEditor\CropPresetGroup;
ImageEditor::make('image_path')
->cropPresetFolders([
CropPresetFolder::make('socialMedia')->groups([
CropPresetGroup::make('facebook')->items([
CropPreset::make('fbProfile', width: 180, height: 180)->description('180x180'),
CropPreset::make('fbCover', width: 820, height: 312)->description('820x312'),
]),
CropPresetGroup::make('instagram')->items([
CropPreset::make('igPost', ratio: 1.0)->description('1:1'),
CropPreset::make('igStory', width: 1080, height: 1920)->description('1080x1920'),
]),
]),
])When a crop preset specifies width and height instead of a ratio, you can enable auto-resize to automatically resize the image to those dimensions after cropping:
ImageEditor::make('image_path')
->cropAutoResize()To set the default crop ratio when the editor opens, use ->cropDefaultRatio():
ImageEditor::make('image_path')
->cropDefaultRatio(16 / 9)The default ratio can also be set to 'original', 'ellipse', or 'custom'.
To hide the crop presets entirely, use ->cropNoPresets():
ImageEditor::make('image_path')
->cropNoPresets()Watermark gallery
You can provide a gallery of watermark images that users can choose from in the Watermark tab:
use RalphJSmit\Filament\Upload\Support\ImageEditor\WatermarkImage;
ImageEditor::make('image_path')
->watermarkGallery([
WatermarkImage::make('https://example.com/watermark-logo.png'),
WatermarkImage::make(
'https://example.com/watermark-large.png',
'https://example.com/watermark-thumb.png',
),
])The second argument to WatermarkImage::make() is an optional preview URL used as a thumbnail in the gallery list for better performance.
To hide the text watermark option and only allow image watermarks, use ->watermarkHideText():
ImageEditor::make('image_path')
->watermarkHideText()Annotation defaults
You can customize the default fill color, stroke color, stroke width, and opacity for all annotation tools:
ImageEditor::make('image_path')
->annotationDefaults([
'fill' => '#3b82f6',
'stroke' => '#1e40af',
'strokeWidth' => 2,
'opacity' => 0.9,
])Text
You can customize which fonts are available in the text annotation tool and the default font size:
ImageEditor::make('image_path')
->textFonts(['Arial', 'Georgia', 'Courier New', 'Verdana'])
->textFontSize(24)Make sure the fonts you provide are available in the user's browser. System fonts like Arial and Georgia work out of the box. Custom fonts must be loaded separately in your application.
Rotate
You can customize the rotation angle step and the rotation component type:
ImageEditor::make('image_path')
->rotateAngle(45)
->rotateComponentType('slider')The component type can be 'slider' or 'buttons'.
Save defaults
You can set the default file type and quality used when saving edited images:
ImageEditor::make('image_path')
->defaultSavedImageType('webp')
->defaultSavedImageQuality(0.9)The supported image types are 'png', 'jpeg', 'jpg', and 'webp'. The quality value ranges from 0.1 to 1 and only applies to jpeg, jpg, and webp formats.