svelte-chop-chop

Headless-first image cropping and editing SDK for Svelte 5. Zero dependencies beyond Svelte.

Documentation & Demo →

Features

• <Cropper> — Lightweight crop component with handles, grid overlays, and transforms
• <ImageEditor> — Full-featured editor with plugin-driven toolbar
• Headless composables — createCropper and createImageEditor for fully custom UI
• Plugin system — filters, finetune, frame, watermark, resize (all opt-in)
• Presets — profilePicture, coverPhoto, productImage
• Three themes — default, dark, minimal (CSS custom properties)
• Zero runtime dependencies — peer dep: svelte ^5.0.0 only

Install

npm install @we-are-singular/svelte-chop-chop

Quick Start

Cropper

<script lang="ts">
  import { Cropper } from '@we-are-singular/svelte-chop-chop';
  import '@we-are-singular/svelte-chop-chop/themes/default';
</script>

<Cropper src="/photo.jpg" aspectRatio={16 / 9} style="height: 400px;" />

Image Editor

<script lang="ts">
  import { ImageEditor } from '@we-are-singular/svelte-chop-chop';
  import { pluginFilters } from '@we-are-singular/svelte-chop-chop/plugins/filters';
  import { pluginFinetune } from '@we-are-singular/svelte-chop-chop/plugins/finetune';
  import { pluginFrame } from '@we-are-singular/svelte-chop-chop/plugins/frame';
  import { pluginWatermark } from '@we-are-singular/svelte-chop-chop/plugins/watermark';
  import { pluginResize } from '@we-are-singular/svelte-chop-chop/plugins/resize';
  import type { ExportResult } from '@we-are-singular/svelte-chop-chop';
  import '@we-are-singular/svelte-chop-chop/themes/default';

  function handleExport(result: ExportResult) {
    const url = URL.createObjectURL(result.blob!);
    const a = document.createElement('a');
    a.href = url;
    a.download = 'edited.jpg';
    a.click();
    URL.revokeObjectURL(url);
  }
</script>

<ImageEditor
  src="/photo.jpg"
  plugins={[pluginFilters(), pluginFinetune(), pluginFrame(), pluginWatermark(), pluginResize()]}
  onexport={handleExport}
  style="height: 500px;"
/>

Cropper Props

Bindable: coordinates (CropCoordinates), transforms (TransformState) Events: onchange, onready, onerror

Headless Usage

import { createCropper } from "@we-are-singular/svelte-chop-chop/headless";
import { createImageEditor } from "@we-are-singular/svelte-chop-chop";

// Lightweight cropper (export uses full resolution — original image pixels)
const cropper = createCropper({ aspectRatio: 16 / 9 });
await cropper.loadImage("/photo.jpg");
const result = await cropper.export({ format: "image/webp", quality: 0.9 });

// Full editor
const editor = createImageEditor({ plugins: [pluginFilters()] });
await editor.loadImage("/photo.jpg");
editor.applyFilter("clarendon");
editor.rotate(90);
const result = await editor.export({ format: "image/webp", quality: 0.9 });
// result.blob, result.dataURL, result.canvas, result.coordinates

Plugins

Custom Plugin

import type { ChopPlugin } from "@we-are-singular/svelte-chop-chop";

const myPlugin: ChopPlugin = {
  name: "my-plugin",
  setup(ctx) {
    ctx.registerAction({
      id: "my-action",
      label: "My Action",
      group: "tabs",
      execute: () => ctx.showPanel("my-panel"),
    });

    ctx.registerPostProcessor(async (drawCtx, canvas) => {
      // draw on canvas at export time
    });

    return () => {
      /* cleanup */
    };
  },
};

Presets

import { profilePicture, coverPhoto, productImage } from '@we-are-singular/svelte-chop-chop/presets';

// Spread into component props
<Cropper src="/photo.jpg" {...profilePicture} />

Theming

@import "@we-are-singular/svelte-chop-chop/themes/default"; /* or dark, minimal */

Override any CSS custom property:

:root {
  --chop-bg: #1a1a2e;
  --chop-stencil-border: #e94560;
  --chop-toolbar-active: #e94560;
}

Available variables: --chop-bg, --chop-canvas-bg, --chop-color, --chop-border-radius, --chop-stencil-border, --chop-stencil-border-active, --chop-grid-color, --chop-overlay, --chop-toolbar-bg, --chop-toolbar-color, --chop-toolbar-active, --chop-transition-duration, --chop-transition-easing

Package Exports

Keyboard Shortcuts

License

MIT © We Are Singular