Plugin options

Every first-party plugin can be tuned: which presets a filter offers, which aspect ratios a crop allows, whether a watermark is locked. Options follow two rules:

• They tune behaviour and constrain edits. They never carry pixel data. A custom filter is written to the edit log as preset: 'custom' with its matrix, stickers and fonts are assets, so a render never depends on options and the parity guarantee holds.
• Constraints are enforced on both sides when you ask for it. By default options only shape the tools. Set enforce: true on a plugin (or lock: true on the watermark) and every edit log that breaks the constraints is rejected with OPTION_VIOLATION (HTTP 400 on the server), even from a modified client. Register the same options on the server for the guarantee to hold.

Two ways to configure

Compose plugins yourself with configure():

import { defaultPlugins, filterPlugin, cropPlugin } from '@sealpixel/plugins';

const plugins = defaultPlugins.map((p) => {
  if (p.id === 'filter')
    return filterPlugin.configure({
      presets: ['grayscale', 'sepia', { name: 'brand', label: 'Brand', matrix: BRAND_MATRIX }],
      defaultStrength: 0.8,
    });
  if (p.id === 'crop') return cropPlugin.configure({ aspects: [{ label: 'crop.aspect.square', value: 1 }], enforce: true });
  return p;
});
editor.plugins = plugins;

Or pass a pluginOptions map and let the editor apply it to the default plugins:

Element

<sealpixel-editor plugin-options='{"filter":{"presets":["grayscale","sepia"]},"crop":{"rotation":false}}'></sealpixel-editor>

React

<SealpixelEditor src={file} pluginOptions={{ filter: { presets: ['grayscale', 'sepia'] }, crop: { rotation: false } }} />

Vue

<SealpixelEditor :src="file" :plugin-options="{ filter: { presets: ['grayscale', 'sepia'] }, crop: { rotation: false } }" />

Svelte

<SealpixelEditor {src} pluginOptions={{ filter: { presets: ['grayscale', 'sepia'] }, crop: { rotation: false } }} />

Astro

<SealpixelEditor src="/photo.jpg" pluginOptions={{ filter: { presets: ['grayscale', 'sepia'] }, crop: { rotation: false } }} />

Server

createSealpixelHandler({
  plugins: defaultPlugins,
  pluginOptions: { filter: { presets: ['grayscale', 'sepia'] }, crop: { rotation: false } },
  sources: [inlineSource()],
});

Unknown keys, unknown plugin ids and values outside the schema throw at configuration time. The map wins over a hand-configured plugin with the same id.

Try it

The filter offers two built-in presets and one custom matrix; the crop is square only, without rotation. Edit the JSON below the editor.

Round avatars

cropPlugin.configure({ shape: 'circle', reset: false, enforce: true });

shape: 'circle' fixes the aspect to 1, shows a round mask in the crop gizmo and writes mask: 'circle' into the crop operation. The core keeps only the inscribed circle with an anti-aliased edge and makes the outside transparent, identically in the browser and on the server; PNG and WebP exports keep the transparency, JPEG flattens onto the background colour. Because the mask lives in the edit log, a saved log renders the same everywhere without knowing the option. reset: false removes the "Reset crop" button (and, with enforce, rejects crop.reset), so a signup flow cannot lose its round shape; with reset allowed, resetting a circle crop restores a full round crop instead of dropping the mask.

Defaults become operations

Options such as filter.defaultPreset, finetune.defaults, crop.defaultAspect, fill.default and watermark.defaults.source are applied when a source loads with an empty edit log. The editor dispatches the corresponding operations, so the defaults are visible in the log and travel with it. A saved log is never altered.

Locked watermark

watermarkPlugin.configure({
  lock: true,
  defaults: { source: { kind: 'text', text: '© ACME', font: 'font.roboto', color: [1, 1, 1, 1] }, anchor: 'br', opacity: 0.5 },
});

With lock, the tool shows the watermark as fixed, every watermark.set that deviates and every watermark.clear is rejected, and export or a server render fail while the watermark is missing or altered. Register the same options on the server for the guarantee to hold.

Reference

The options reference lists every option with type, default and description, generated from the schemas.

Third-party plugins

definePlugin({ options: { schema, defaults, describe }, validate, validateDocument, initialOps }) gives your plugin the same surface. See Writing a plugin.