filerobot-image-editor-vue3

A Vue 3 wrapper component for the Filerobot Image Editor — a powerful, browser-based image editor with cropping, resizing, annotation, finetune, filters, and watermark tools.

Installation

npm install filerobot-image-editor-vue3

Basic Usage

Wrap the component in a sized container. The editor fills 100% of its parent's height and width.

<script lang="ts" setup>
import { FilerobotImageEditorVue3, TABS, TOOLS } from 'filerobot-image-editor-vue3'
import type { IFilerobotImageEditorConfig } from 'filerobot-image-editor-vue3'

const editorConfig: IFilerobotImageEditorConfig = {
  source: 'https://example.com/image.jpg',
  tabsIds: [TABS.ADJUST, TABS.FINETUNE, TABS.ANNOTATE, TABS.FILTERS],
  defaultTabId: TABS.ADJUST,
  language: 'en',
  onSave: (savedImageData) => {
    console.log(savedImageData.imageBase64)
  },
}
</script>

<template>
  <!-- The editor fills its parent — give the parent an explicit height -->
  <div style="height: 600px; width: 100%;">
    <FilerobotImageEditorVue3 :config="editorConfig" />
  </div>
</template>

Important: The editor stretches to fill 100% of its parent's height. Always give the parent container an explicit height (e.g. height: 600px or height: 100vh). Without this the editor will collapse.

Props

| Prop | Type | Required | Description | |----------|-------------------------------|----------|--------------------------------------| | config | IFilerobotImageEditorConfig | ✅ | Full configuration object (see below) |

Exposed

| Name | Type | Description | |-------------------------------|-------|------------------------------------------| | filerobotImageEditorInstance | ref | Direct access to the underlying library instance |

Configuration Reference

Core

| Option | Type | Description | |--------|------|-------------| | source | string \| HTMLImageElement | Required. The image URL or element to edit. | | theme | Theme | Custom UI theme from @scaleflex/ui. | | loadableDesignState | ImageDesignState | Pre-load a previously saved design state. |

Tabs & Tools

| Option | Type | Description | |--------|------|-------------| | tabsIds | EditorTab[] | Ordered list of tabs to show. Defaults to all. Values: TABS.ADJUST, TABS.FINETUNE, TABS.FILTERS, TABS.WATERMARK, TABS.ANNOTATE, TABS.RESIZE. | | defaultTabId | EditorTab | Tab to activate on load. | | defaultToolId | EditorTool | Tool to activate within the default tab. |

Saving

| Option | Type | Description | |--------|------|-------------| | onSave | (data, designState) => void | Called when the user saves. data.imageBase64 contains the result. | | onBeforeSave | (data) => void \| false | Called before saving. Return false to cancel. | | showSaveButton | boolean | Show the default Save button. Default: true. | | disableSaveIfNoChanges | boolean | Disable Save when nothing has changed. | | removeSaveButton | boolean | Completely remove the Save button from the DOM. | | closeAfterSave | boolean | Close the editor after saving. | | defaultSavedImageName | string | Default filename for downloads. | | defaultSavedImageType | 'png' \| 'jpeg' \| 'jpg' \| 'webp' | Output format. | | defaultSavedImageQuality | number | Output quality (0–1). | | savingPixelRatio | number | Pixel ratio for the exported image. | | previewPixelRatio | number | Pixel ratio for the editor preview canvas. | | forceToPngInEllipticalCrop | boolean | Force PNG output when using elliptical crop. | | moreSaveOptions | SaveOption[] | Additional entries in the save dropdown. |

Lifecycle Callbacks

| Option | Type | Description | |--------|------|-------------| | onModify | (state: ImageDesignState) => void | Fired on every design change. | | onClose | (reason, hasUnsavedChanges) => void | Fired when the editor is closed. |

General Editor Settings

| Option | Type | Description | |--------|------|-------------| | avoidChangesNotSavedAlertOnLeave | boolean | Suppress the browser "unsaved changes" dialog. | | resetOnImageSourceChange | boolean | Reset state when source changes. | | showBackButton | boolean | Show a Back button in the top bar. | | observePluginContainerSize | boolean | Auto-adjust layout on container resize. | | showCanvasOnly | boolean | Hide all UI, show only the canvas. | | useZoomPresetsMenu | boolean | Show the zoom preset menu. | | disableZooming | boolean | Disable all zooming. | | noCrossOrigin | boolean | Set crossOrigin=anonymous on the image. | | backgroundColor | string | Editor workspace background color. |

UI Visibility — Top Bar Buttons

| Option | Type | Description | |--------|------|-------------| | noUndoButton | boolean | Hide the Undo button from the top bar. | | noRedoButton | boolean | Hide the Redo button from the top bar. | | noResetButton | boolean | Hide the Reset button from the top bar. |

Custom Extension: Sidebar Undo Tab

| Option | Type | Description | |--------|------|-------------| | withUndoButtonAsTab | boolean | Custom Extension. Injects an Undo tab into the sidebar tab list, synced with the top-bar Undo button's disabled state. Useful when the top bar is hidden. | | noUndoButtonAsTab | boolean | Hides the native undo/history tab from the sidebar (available in some library versions). |

Crop Options

Crop?: {
  ratio?: 'original' | 'custom' | 'ellipse' | number
  noPresets?: boolean
  noRotate?: boolean
  noFlipX?: boolean
  noFlipY?: boolean
  withResize?: boolean
  minWidth?: number
  minHeight?: number
  maxWidth?: number
  maxHeight?: number
  autoResize?: boolean
  lockCropAreaAt?: 'top-left' | 'top-center' | ... // 9 positions
  presetsItems?: CropPresetItem[]
  presetsFolders?: CropPresetFolder[]
}

| Option | Description | |--------|-------------| | ratio | Default crop ratio. | | noPresets | Hide the crop presets/ratio menu. | | noRotate | Hide the Rotate button from the Crop toolbar. | | noFlipX | Hide the Flip X button from the Crop toolbar. | | noFlipY | Hide the Flip Y button from the Crop toolbar. | | withResize | Custom Extension. Embeds Resize as a sub-step inside the Crop tab. Hides the standalone Resize sidebar tab and adds a Resize button to the Crop toolbar and a Back to Crop button to the Resize toolbar. |

Finetune Options

All are boolean. Setting to true hides that control.

| Option | Hides | |--------|-------| | noBrightness | Brightness slider | | noContrast | Contrast slider | | noHueSaturationValue | Hue / Saturation / Value sliders | | noWarmth | Warmth slider | | noBlur | Blur slider | | noThreshold | Threshold slider | | noPosterize | Posterize slider | | noPixelate | Pixelate slider | | noNoise | Noise slider |

Filters

Pass an allow-list of filter names to restrict what the user sees:

Filters: ['Original', 'Black & White', 'Sepia', 'Solarize', 'Invert']

Annotation Tools

All annotation types extend AnnotationsCommon:

| Common Option | Description | |---------------|-------------| | noFill | Hide fill color picker. | | noOpacity | Hide opacity control. | | noStroke | Hide stroke control. | | noShadow | Hide shadow control. | | noPosition | Hide position control. |

Text — Additional Options

| Option | Description | |--------|-------------| | noFontFamily | Hide font family selector. | | noFontSize | Hide font size control. | | noBold | Hide bold toggle. | | noItalic | Hide italic toggle. | | noAlignment | Hide text alignment control. | | noTextSpacing | Hide letter/line spacing controls. | | fonts | Custom font list: string[] or { label, value }[]. | | text | Default text for new text annotations. |

Watermark Options

| Option | Description | |--------|-------------| | gallery | Array of preset watermark image URLs. | | textScalingRatio | Scale ratio for text watermarks (0–1). | | imageScalingRatio | Scale ratio for image watermarks (0–1). | | hideTextWatermark | Hide the text watermark option. | | noOpacity | Hide opacity control for watermarks. |

Localization

| Option | Type | Description | |--------|------|-------------| | language | 'en' \| 'fr' \| ... | Editor UI language. Supported: en, fr, de, it, pt, es, nl, pl, ro. | | translations | object | Override or extend any translation key. See src/utils/lang/en.ts for all keys. |

Example — override a tab label:

translations: {
  adjustTab: 'Crop & Adjust',
  resizeTab: 'Image Size',
}

Cloudimage Integration

| Option | Type | Description | |--------|------|-------------| | useCloudimage | boolean | Enable Cloudimage processing mode. | | cloudimage | object | Cloudimage-specific config (token, domain, version, etc.). | | useBackendTranslations | boolean | Use translations from the Cloudimage backend. |

Layout Requirements

The component renders to 100% of its parent's size. You must give the parent an explicit height:

<!-- ✅ Correct -->
<div style="height: 100vh;">
  <FilerobotImageEditorVue3 :config="config" />
</div>

<!-- ❌ Will collapse — no height defined -->
<div>
  <FilerobotImageEditorVue3 :config="config" />
</div>

Full Example

<script lang="ts" setup>
import { ref } from 'vue'
import { FilerobotImageEditorVue3, TABS, TOOLS } from 'filerobot-image-editor-vue3'
import type { IFilerobotImageEditorConfig } from 'filerobot-image-editor-vue3'

const editorRef = ref(null)

const config: IFilerobotImageEditorConfig = {
  source: 'https://example.com/photo.jpg',

  tabsIds: [TABS.ADJUST, TABS.FINETUNE, TABS.FILTERS, TABS.ANNOTATE],
  defaultTabId: TABS.ADJUST,

  Crop: {
    ratio: 'custom',
    noRotate: true,
    noFlipX: true,
    noFlipY: true,
    withResize: true,   // Embeds Resize inside the Crop tab
  },

  Finetune: {
    noBrightness: false,
    noBlur: true,
    noNoise: true,
    noPosterize: true,
    noPixelate: true,
    noThreshold: true,
  },

  Filters: ['Original', 'Black & White', 'Sepia'],

  Text: {
    noFontFamily: true,
    noBold: true,
    noItalic: true,
    text: 'Add text...',
  },

  language: 'en',
  withUndoButtonAsTab: true,  // Adds Undo to the sidebar
  noUndoButton: true,
  noRedoButton: true,
  noResetButton: true,

  showSaveButton: false,
  disableSaveIfNoChanges: true,
  avoidChangesNotSavedAlertOnLeave: true,

  onSave: (data) => {
    console.log('Saved:', data.fullName, data.imageBase64)
  },
}
</script>

<template>
  <div style="height: 100vh; width: 100%;">
    <FilerobotImageEditorVue3 ref="editorRef" :config="config" />
  </div>
</template>

Development

npm install       # Install dependencies
npm run dev       # Start dev server with hot-reload
npm run build     # Build the library bundle
npm run lint      # Lint source files

License

MIT — see LICENSE for details.