Configuration

Every aspect of the editor is driven by a single config object passed to <ImageEditor> or <ImageEditorModal>. This page is the top-level reference — each tool has its own guide with the full option tables.

Overview

Pass a config prop to customize behavior. Every field is optional.

<ImageEditor
  src="/photo.jpg"
  config={{
    tools: ["crop", "adjust", "filter", "text", "shapes"],
    defaultTool: "crop",
    export: {
      formats: ["png", "jpeg", "webp"],
      defaultFormat: "png",
      quality: 0.92,
    },
  }}
  onSave={handleSave}
/>

ImageEditorConfig

Option	Type	Default	Description
`tools`	`ImageEditorToolId[]`	all	Tools to show, in order. See Customize the Toolbar.
`defaultTool`	`ImageEditorToolId \| null`	`null`	Tool activated on load.
`theme`	`ThemeConfig`	`{ preset: "dark" }`	Colors, radius, and font. See Theming.
`colors`	`string[]`	built-ins	Swatch palette (hex) shared by every color picker.
`crop`	`CropToolConfig`	—	Crop Tool options.
`adjust`	`AdjustToolConfig`	—	Adjust Tool options.
`filter`	`FilterToolConfig`	—	Filter Tool options.
`text`	`TextToolConfig`	—	Text Tool options.
`shapes`	`ShapesToolConfig`	—	Shapes Tool options.
`image`	`ImageToolConfig`	—	Image upload limits.
`ui`	`UIConfig`	—	Chrome and sidebar options (below).
`export`	`ExportConfig`	—	Output formats and save behavior. See Export & Save.
`customTools`	`CustomTool[]`	—	Register your own tools. See Add a Custom Tool.
`locale`	`string`	`"en"`	Active locale. See Localize the UI.
`translations`	`Record<string, string>`	—	Override individual translation strings.
`translateFn`	`(key: string) => string`	—	Custom lookup, called instead of the built-in dictionary.

Available tools

Tool	ID	Description
Crop	`"crop"`	Crop, rotate, flip, resize with presets
Adjust	`"adjust"`	Brightness, contrast, saturation, etc.
Filter	`"filter"`	Instagram-style photo filters
Text	`"text"`	Rich styles and editable layered compositions in a searchable gallery
Shapes	`"shapes"`	Filled, outlined, gradient, image, and abstract graphics in searchable categories
Image	`"image"`	Image overlay annotations

Text presets

config.text controls typography defaults and the Text gallery. See Configure Text for authored block, run-style, and composition examples.

Option	Type	Default	Description
`fonts`	`string[]`	built-ins	Font families shown in text controls.
`defaultFontFamily`	`string`	first font	Family for new text.
`defaultFontSize`	`number`	`24`	Reference size at a 1080px canvas.
`defaultColor`	`string`	`"#ffffff"`	Fill for new text when the preset omits one.
`presetGroups`	`PresetGroup<TextPreset>[]`	built-ins	Replace the complete built-in gallery.
`additionalPresetGroups`	`PresetGroup<TextPreset>[]`	—	Append groups; matching group ids merge presets.
`presets`	`TextStylePreset[]`	—	Deprecated flat compatibility list.

Shape presets

config.shapes controls the Shapes gallery and insertion defaults. See Configure Shapes for gradients, image fills, strokes, and custom paths.

Option	Type	Default	Description
`presetGroups`	`PresetGroup<ShapePreset>[]`	built-ins	Replace the complete built-in gallery.
`additionalPresetGroups`	`PresetGroup<ShapePreset>[]`	—	Append groups; matching group ids merge presets.
`presets`	`string[]`	—	Deprecated shape-kind compatibility list.
`defaultColor`	`string`	`"#3b82f6"`	Fallback color for new shapes.
`defaultOpacity`	`number`	`1`	Starting opacity from `0` to `1`.
`defaultSize`	`number`	`0.5`	Canvas-relative size when a preset omits `sizeFraction`.

Preset authoring types, including PresetGroup, TextPreset, ShapePreset, and composition types, are exported from @editx/image-editor.

Export

config.export controls the save step. Full walkthrough in Export & Save.

Option	Type	Default	Description
`formats`	`("png" \| "jpeg" \| "webp")[]`	all	Formats offered in the export dialog.
`defaultFormat`	`"png" \| "jpeg" \| "webp"`	first	Pre-selected format.
`quality`	`number`	`0.92`	Encoder quality (0–1) for lossy formats.
`closeAfterSave`	`boolean`	`false`	Call `onClose` after a successful export.
`filename`	`string`	derived	Base filename for the built-in download.

UI

config.ui tunes the editor chrome. See Customize the Toolbar and Customize the Chrome.

Option	Type	Default	Description
`toolSidebar.compact`	`boolean`	`false`	Collapse the tool rail to icons only.
`toolSidebar.groupSeparators`	`boolean`	`true`	Dividers between tool groups.
`title`	`string`	—	Title shown in the topbar.
`showTitle`	`boolean`	—	Toggle the topbar title.
`showCloseButton`	`boolean`	auto	Show the close (X) button.
`showBackButton`	`boolean`	`false`	Use a back arrow instead of X.
`unsavedChangesWarning`	`boolean`	`true`	Confirm before closing with unsaved changes.

Next steps

API Reference — component props, slots, and events.
Customize the Toolbar — choose which tools appear.
Playground — experiment with every option live.