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 the server handler that 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 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[]	all first-party plugins	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).
editLog	edit log	–	Controlled mode: the host owns the log and receives sealpixel:change.
output	{ format, quality }	image/png	Format of Download and Export.
server-endpoint · server	URL · { endpoint, headers, fetch }	–	Server rendering for large images and download({ via: 'server' }).
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.

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 { createSealpixelHandler, inlineSource } from '@sealpixel/server';
import { defaultPlugins } from '@sealpixel/plugins';

// The same options on the server: a log with a rotated or non-round crop is rejected (400 OPTION_VIOLATION).
export default createSealpixelHandler({
  plugins: defaultPlugins,
  pluginOptions: options,
  sources: [inlineSource()],
});

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. Register the same pluginOptions on the server; the UI hides, the server rejects.
• Configuration is per element. Two editors on one page can have different plugins, options and languages.