Configuration

Everything a host can set on the editor lives in three places: attributes and properties on <sealpixel-editor> (props in the wrappers), the plugin set with its options, and @sealpixel/render on your server, which enforces the same options. The stage, gestures and layouts configure themselves; there is no settings object beyond these.

Attributes and properties

Attribute · property	Values	Default	What it does
src	File, Blob, Uint8Array, URL string, SourceDescriptor	–	The image. Setting it creates or resets the session.
theme	dark · light · auto	dark	Colour scheme; tokens override single colours, see Theming.
locale	en · de · fr · es · pt · ja · region variants	en	Interface language; dictionary overrides strings.
active-tool · activeTool	plugin id	first tool	Tool shown on load, e.g. crop.
show-history · showHistory	all · buttons · none	all	Undo, redo and the timeline; none also disables the undo and redo shortcuts.
show-export · showExport	auto · always · never	auto	Export button; auto shows it while a sealpixel:process listener exists.
show-download · showDownload	always · never	always	Download button.
download-label · downloadLabel	text	localized	Replaces the Download label.
plugin-options · pluginOptions	{ pluginId: partialOptions } (JSON in the attribute)	–	Configures the plugins, see below.
plugins	AnyPlugin[]	defaultPlugins (allPlugins adds sticker, watermark and assist)	Which plugins (and thus tools) exist. Keep fill; it has no tool.
tools	{ pluginId: UiTool }	built-in tools	Replaces or adds the UI of a plugin.
default-edit-log · defaultEditLog	edit log	–	Applied once on load (uncontrolled). null is the same as no log.
editLog	edit log	–	Controlled mode: the host owns the log and receives sealpixel:change. null is the same as no log.
output	{ format, quality }	image/png	Format of Download and Export.
limits	{ maxClientMegapixels, maxClientBytes } (JSON in the attribute)	16 · 50e6	How much of the original stays in the browser. Above the megapixel limit the image is not resident: the preview works on a working copy, Export and Download are disabled, and your server renders the original, see Working copy. Above the byte limit the image does not load.
renderer	Renderer	worker renderer	Bring your own renderer, e.g. a shared worker.
assets	AssetResolver	fetch resolver	Where fonts and images come from.
dictionary	flat map	shipped locale	Custom or partial translations, merged over the shipped locale, see Locale.

Events: sealpixel:ready, sealpixel:change, sealpixel:process, sealpixel:error, sealpixel:load. Methods: export(), download(), undo(), redo(), timeTravel(), getEditLog(), getSession().

One configuration, every framework

A round profile-photo cropper: two tools, a locked square circle crop, no timeline, no Export, a custom Download label.

Element

<sealpixel-editor
  theme="light"
  active-tool="crop"
  show-history="buttons"
  show-export="never"
  download-label="Save avatar"
  plugin-options='{"crop":{"shape":"circle","reset":false,"aspects":[{"label":"crop.aspect.square","value":1}],"defaultAspect":1,"rotation":false,"flip":false,"enforce":true},"finetune":{"controls":["brightness","contrast"]}}'
></sealpixel-editor>
<script type="module">
  import { defaultPlugins } from '@sealpixel/element';
  const editor = document.querySelector('sealpixel-editor');
  editor.plugins = defaultPlugins.filter((p) => ['crop', 'finetune', 'fill'].includes(p.id));
  editor.src = '/portrait.jpg';
</script>

React

import { SealpixelEditor } from '@sealpixel/react';
import { defaultPlugins } from '@sealpixel/plugins';

const plugins = defaultPlugins.filter((p) => ['crop', 'finetune', 'fill'].includes(p.id));
const options = {
  crop: { shape: 'circle', reset: false, aspects: [{ label: 'crop.aspect.square', value: 1 }], defaultAspect: 1, rotation: false, flip: false, enforce: true },
  finetune: { controls: ['brightness', 'contrast'] },
};

<SealpixelEditor
  src={file}
  theme="light"
  activeTool="crop"
  showHistory="buttons"
  showExport="never"
  downloadLabel="Save avatar"
  plugins={plugins}
  pluginOptions={options}
/>

Vue

<SealpixelEditor
  :src="file"
  theme="light"
  active-tool="crop"
  show-history="buttons"
  show-export="never"
  download-label="Save avatar"
  :plugins="plugins"
  :plugin-options="options"
/>

Svelte

<SealpixelEditor
  {src}
  theme="light"
  activeTool="crop"
  showHistory="buttons"
  showExport="never"
  downloadLabel="Save avatar"
  {plugins}
  pluginOptions={options}
/>

Astro

<SealpixelEditor
  src="/portrait.jpg"
  theme="light"
  activeTool="crop"
  showHistory="buttons"
  showExport="never"
  downloadLabel="Save avatar"
  pluginOptions={options}
/>

Server

import { createRenderer } from '@sealpixel/render';
import { defaultPlugins } from '@sealpixel/plugins';

// The same plugins and options as the editor: render() rejects a log with a rotated or non-round crop (OPTION_VIOLATION).
const plugins = defaultPlugins.filter((p) => ['crop', 'finetune', 'fill'].includes(p.id));
export const renderer = createRenderer({ plugins, pluginOptions: options });

Plugin options

pluginOptions tunes what a tool offers and, with enforce: true, what an edit log may contain. Strengths and sizes are configuration, not controls: a new redaction uses redact.defaultAmount, a preset blends with filter.defaultStrength, a watermark takes watermark.defaults.opacity, a frame frame.defaults.thickness. Defaults such as crop.defaultAspect or filter.defaultPreset become operations when an image loads, so they travel with the log.

Every option with type, default and description: Options reference. The concepts and the enforcement contract: Plugin options.

Live: three configurations

The starter below switches one editor between a profile-photo cropper, a marketing studio and a German redaction desk. Each is nothing but attributes, a plugin subset and a pluginOptions map; the current one is printed under the editor.

Rules of thumb

• Options never carry pixels. Custom filter matrices, stickers and fonts go into the edit log or into assets, so a saved log renders the same without knowing the options.
• Enforce on both sides. Pass the same pluginOptions to createRenderer on your server; the UI hides, the renderer rejects.
• Configuration is per element. Two editors on one page can have different plugins, options and languages.