Images

Pictures come from the user's computer, from stock photo services, or from an AI model. On the page, the user can crop, fit, and filter a picture, and remove its background.

SetupCopy Anchor Link

Upload, crop, fit modes, and filters work with no setup. The other options need a key, a server, or an AI provider, which you pass as props.

import { ImageEditor } from '@layermetry/media-editor/react';

export default function App() {
  return (
    <div style={{ position: 'fixed', inset: 0 }}>
      <ImageEditor
        licenseKey="YOUR_LICENSE_KEY"
        onClose={() => console.log('The editor was closed')}
        onExport={(file) => console.log(`Exported ${file.name}`)}
        // Background removal: your media server.
        mediaApiUrl="https://media.example.com"
        // Stock photos: your Pexels and Unsplash keys.
        stockMediaApis={{
          pexels: { apiKey: 'YOUR_PEXELS_KEY' },
          unsplash: { apiKey: 'YOUR_UNSPLASH_ACCESS_KEY', showAttribution: true },
        }}
        // Image generation and AI image editing: your AI proxy.
        ai={{ endpointUrl: 'https://api.example.com/ai' }}
      />
    </div>
  );
}

UploadCopy Anchor Link

The Upload Images button in the upload panel opens the file picker. The user can choose several files at once.

The panel lists JPG, PNG, GIF, and WebP. A file that is not an image is refused with the message "Invalid file type".

A new picture is placed with the Fit mode, so the whole picture shows on the page.

View full size

Stock photosCopy Anchor Link

With stockMediaApis set, the upload panel shows a Stock Images tab, with one tab for each service. A search asks for pictures in the orientation of the page: landscape, portrait, or square.

stockMediaApis={{
  pexels: { apiKey: 'YOUR_PEXELS_KEY' },
  unsplash: { apiKey: 'YOUR_UNSPLASH_ACCESS_KEY', showAttribution: true },
}}

Unsplash requires showAttribution: true, so the photographer's name is shown with each picture.

CropCopy Anchor Link

Crop shows part of a picture. Select a picture and press Crop in the toolbar above the page, or choose Crop in the right-click menu. In the compact layout, Crop is a chip under the picture. A frame opens over the picture. Drag the frame or its handles to choose the part that shows.

Press Done, press Enter, or click outside the frame to apply the crop. Press Cancel or Esc to leave the picture as it was. Clear crop shows the whole picture again. A crop is one step to undo, and the exported file shows exactly the same part of the picture.

A saved design keeps the crop in a crop field on the picture, { x, y, width, height }, counted in the picture's own pixels, not in page pixels. Store it with the rest of the record.

Fit modesCopy Anchor Link

A fit mode decides how a picture fills the page. Select a picture and press Image Fitting Options in the toolbar above the page.

View full size

Filters and adjustmentsCopy Anchor Link

Select a picture and open the Effects panel. Four filters switch on and off: Grayscale, Sepia, Invert, and Emboss.

Eleven adjustments take a number:

Filters and adjustments appear in the exported file.

View full size

Resize handlesCopy Anchor Link

A selected picture, GIF, or sticker has eight resize handles: four at the corners and four at the sides. All eight keep the shape of the item. A cropped picture keeps the shape of its crop. A turned item grows along its own edges.

When the user drags a side handle, the item grows equally on both sides of the dragged edge. The opposite edge stays where it is. When the user holds Alt (Option on a Mac), the item grows around its middle.

To stretch an item on purpose, hold Shift while dragging a side handle or a corner handle. The user can press or release Shift in the middle of a drag. The change takes effect at once, and releasing Shift brings back the shape that the item had when the drag started.

Text, shapes, lines, and a selection that mixes these with pictures keep their earlier behavior. A very wide or very tall item reaches the smallest size sooner, because its short side shrinks with it. For example, a banner of 1000 × 20 cannot be made narrower than 250 from a side handle without Shift.

On a phone there is no Shift key. To change the shape of a picture there, use Stretch in the Fit options, which fits the picture to the shape of the page, or crop the picture. See Fit modes.

Background removalCopy Anchor Link

Select a picture and press Remove Background in the toolbar, or choose Remove background in the right-click menu. The editor replaces the picture with the one your server returns, at the same place and size.

Image generationCopy Anchor Link

With ai set, the upload panel shows Generate image. The user describes the picture and presses Generate.

The results appear in the box. Choose a picture and select Add to canvas to place it. Generate more appends results; Try again replaces the current choices. Every picture made in the session stays in the Generated tab.

ai={{ endpointUrl: 'https://api.example.com/ai' }}

AI image editingCopy Anchor Link

Select a picture and press Edit with AI in the toolbar, or choose Edit with AI… in the right-click menu. The user describes the change, for example "put two passengers in the boat", and presses Generate.

The box offers starts such as Change the background and Add something. The first suggestion previews on the picture. Click a card to compare it; choose Original to restore the source. Closing the box keeps the selected result as one editing action, with one Undo step.

The request has "operation": "imageEdit" and carries the picture in input.source. The answer has the same { items: [{ url }] } format as image generation.

When you pass onUploadAsset, the editor gives it the new picture before the picture is replaced, so the design keeps your own address. Without onUploadAsset, the picture's data is saved inside the design. See Asset storage.

UpscalingCopy Anchor Link

Upscaling will increase the resolution of a picture.

MasksCopy Anchor Link

Masks will hide part of a picture behind a shape.

ConfigurationCopy Anchor Link

EventsCopy Anchor Link

Images have no events of their own. The editor calls onUploadAsset when the user keeps a picture changed with AI. The finished design reaches you through onExport. See Events.

TroubleshootingCopy Anchor Link

Additional resourcesCopy Anchor Link

Watch: open and close cropCopy Anchor Link

Select a picture and choose Crop. Drag the frame to choose what shows, then choose Done.