Choose the tools

Show only the tools you need, set the crop shapes and sizes that fit your site, and limit how long a video can be.

The editor opens photos and videos with the tools that fit each one. You choose which tools it shows, which one it opens on, and the crop shapes your site needs.

Pick the tools

utils lists the tools to show, in order. util is the one the editor opens on.

appendDefaultEditor("#editor", {
  utils: ["crop", "resize"],
  util: "crop",
})

Util	Tool	Photos	Videos
`trim`	Trim	–	Keep one or more parts, mute
`crop`	Crop	Crop, turn, flip and straighten	Crop, turn and flip
`finetune`	Adjust	Brightness, contrast, saturation, exposure, warmth, gamma, clarity and vignette	The same, on every frame
`filter`	Color	Ten looks, each with a strength	The same, on every frame
`annotate`	Draw	Pen, arrows, lines, boxes, ellipses and text	The same, on every frame
`fill`	Fill	A color behind see-through parts and past the edges	–
`redact`	Pixelate	Pixelate or blur the parts your visitor marks	–
`resize`	Resize	Resize to an exact width and height	Resize

The default is all eight, in that order. A util a file can't use is left out for it, so one editor can take both photos and videos. With only one util, set enableUtils: false to hide the tool switcher too.

Choose the looks

The Color tool shows each look on the picture itself. filterOptions picks which looks it offers and what they're called, and filterFunctions adds your own as 4×5 color matrices:

import { appendDefaultEditor, plugin_filter_defaults } from "@mastershot/editor"

appendDefaultEditor("#editor", {
  ...plugin_filter_defaults,
  filterOptions: [
    ["mono", "Black and white"],
    ["warm", "Warm"],
    ["brand", "Our look"],
  ],
  filterFunctions: {
    ...plugin_filter_defaults.filterFunctions,
    // prettier-ignore
    brand: () => [
      1.1, 0, 0,   0, 0.02,
      0,   1, 0,   0, 0,
      0,   0, 0.9, 0, 0,
      0,   0, 0,   1, 0,
    ],
  },
})

The usual looks are vivid, warm, cool, fade, pastel, sepia, vintage, mono, noir and inverted.

Let the crop reach past the picture

With imageCropLimitToImage: false, the crop box can be pulled past the picture's edges, for a square avatar from a wide photo or room around a product. The Fill tool's color fills what the picture doesn't cover, and you can set it from code as imageBackgroundColor, red, green, blue and alpha from 0 to 1:

appendDefaultEditor("#editor", {
  utils: ["crop", "fill"],
  imageCropAspectRatio: 1,
  imageCropLimitToImage: false,
  imageBackgroundColor: [1, 1, 1, 1], // white
})

Without a fill color, those parts stay see-through in a PNG or WebP and turn white in a JPEG.

Crop to a fixed shape

imageCropAspectRatio holds the crop to one shape, as width divided by height:

appendDefaultEditor("#editor", {
  utils: ["crop"],
  imageCropAspectRatio: 1, // square, for avatars
})

Offer a choice of shapes and sizes

cropSelectPresetOptions gives your visitor shapes to choose from. Each is [ratio, label]. A ratio of undefined is a free crop. A [width, height] pair instead of a ratio crops to that shape and saves at that size.

appendDefaultEditor("#editor", {
  cropSelectPresetOptions: [
    [undefined, "Free"],
    [1, "Square"],
    [4 / 5, "Portrait"],
    [16 / 9, "Wide"],
    [[1500, 500], "Banner, 1500 × 500"],
  ],
})

Shapes can also come in groups, as [groupLabel, [[ratio, label], …]]. Set cropEnableSelectPreset: false to hide the shape choice.

Turn off parts of the crop tool

These are all true unless you set them to false, but for flipping up and down, which is off unless you set it to true:

Option	Shows
`cropEnableButtonRotateLeft`	The turn-left button
`cropEnableButtonRotateRight`	The turn-right button
`cropEnableRotationInput`	The straighten dial (photos)
`cropEnableButtonFlipHorizontal`	Flip across
`cropEnableButtonFlipVertical`	Flip up and down (off)
`cropEnableSelectPreset`	The shape button

cropRotationRange sets how far the dial straightens, in radians each way.

Limit a video's length

appendDefaultEditor("#editor", {
  utils: ["trim"],
  imageMaxDuration: 60, // seconds kept, at most
  imageMinDuration: 3, // a shorter video is refused
  trimEnableSplit: true, // keep several parts, joined back to back
})

The buttons around it

Option	Default	Does
`enableToolbar`	`true`	The bar with Undo, Redo, Revert and Done
`enableButtonExport`	`true`	Done
`enableButtonClose`	`false` (modal: `true`)	Cancel, which sends `close`
`enableNavigateHistory`	`true`	Undo and Redo
`enableButtonRevert`	`true`	Revert to the file as it opened
`enableBrowseImage`	`true`	Choose a file, when the editor has none
`enableDropImage`	`true`	Drop a file on it, when it has none
`accept`	`"image/,video/"`	The files it offers to open
`enableHaptics`	`false`	Buzzes the phone as a dial is turned

Without Done, call editor.processImage() from your own button. willClose() runs on Cancel; return false to keep the editor open.

Change the labels

locale sets every word the editor shows. It comes in English, German, French, Spanish, Italian, Brazilian Portuguese and Dutch:

import { appendDefaultEditor, locale_de_de } from "@mastershot/editor"

appendDefaultEditor("#editor", { locale: locale_de_de })

To change a few words, lay your own over a language:

appendDefaultEditor("#editor", {
  locale: {
    ...locale_en_gb,
    labelButtonExport: "Save photo",
    labelBrowse: "Choose a photo",
  },
})

The usual buttons and tools have their own keys: labelButtonExport (Done), labelClose (Cancel), labelButtonUndo, labelButtonRedo, labelButtonRevert, labelReset, labelBrowse, labelWaiting, and cropLabel, trimLabel, finetuneLabel, filterLabel, annotateLabel, fillLabel, redactLabel and resizeLabel for the tools. Log locale_en_gb to see the rest. A label with a {name} in it, such as "Saves at {size}", is filled in by the editor, so keep the {name} when you change it. A key the editor doesn't know is ignored, so labels written for other editors do no harm.

Stuck, or something isn't working? Email [email protected] with what you tried. If a photo or video won't open, send it if you can, and we'll make it work.