ImageCropper

<script lang="ts">
  import { ImageCropper, Button, type ImageCropperApi } from 'sv5ui';

  let api = $state<ImageCropperApi>();
  let preview = $state<string | null>(null);

  async function crop() {
    const result = await api?.crop();
    // result is null when there is nothing to crop, or when the export failed.
    // The reason arrives through onError rather than as a thrown exception.
    if (result) preview = URL.createObjectURL(result.blob);
  }
</script>

<ImageCropper bind:api src={photo} aspect={1} />
<Button label="Crop" onclick={crop} />

{#if preview}
  <img src={preview} alt="Cropped result" />
{/if}

<!-- fixed (default): the frame is centred and immovable. The user drags and
     zooms the image behind it, and the image always covers the frame, so a
     crop can never contain empty edges. This is the model for avatars and
     cover images, and the one that behaves best under a thumb. -->
<ImageCropper src={photo} mode="fixed" aspect={1} />

<!-- box: the image is fitted inside the stage and stays put. The user drags
     the frame itself and its eight handles. Dragging outside the frame still
     pans the image. This is the model for free cropping of documents and
     screenshots, where the whole picture has to stay visible. -->
<ImageCropper src={photo} mode="box" aspect="free" />

<!-- aspect is width / height -->
<ImageCropper src={photo} aspect={1} />        <!-- square -->
<ImageCropper src={photo} aspect={16 / 9} />   <!-- widescreen -->
<ImageCropper src={photo} aspect={4 / 3} />
<ImageCropper src={photo} aspect={3 / 4} />    <!-- portrait -->

<!-- 'free' unlocks both axes, and only means anything in box mode: a fixed
     frame has no handles to resize it with. -->
<ImageCropper src={photo} mode="box" aspect="free" />

<!-- Changing aspect at runtime re-fits the frame around the current centre. -->
<ImageCropper src={photo} aspect={ratio} />

<!-- inset (default): a free frame opens at 80% of the image, so the crop
     region reads as a frame the moment the cropper appears, and the arrow
     keys have room to move it. -->
<ImageCropper src={photo} mode="box" aspect="free" />

<!-- full: the frame starts on the whole image, so confirming without
     dragging keeps everything. Use it wherever a silent crop would be a
     surprise, which is why the Editor crop dialog passes it. -->
<ImageCropper src={photo} mode="box" aspect="free" initialFrame="full" />

<!-- A fixed aspect ignores the prop: there is only one sensible opening
     frame, the largest one that fits. -->
<ImageCropper src={photo} mode="box" aspect={16 / 9} />

<script lang="ts">
  import { ImageCropper } from 'sv5ui';
</script>

<!-- shape="circle" always crops 1:1, so aspect is ignored. -->
<ImageCropper src={photo} shape="circle" mode="fixed" />

<!-- The export is a square image with everything outside the circle
     transparent, so keep the default PNG... -->
<ImageCropper src={photo} shape="circle" output={{ type: 'image/png' }} />

<!-- ...or paint a background under it when the destination has no alpha
     channel. JPEG defaults to a white background for exactly this reason. -->
<ImageCropper
  src={photo}
  shape="circle"
  output={{ type: 'image/jpeg', quality: 0.9, background: '#0f172a' }}
/>

<script lang="ts">
  import { FileUpload, ImageCropper, Button, type ImageCropperApi } from 'sv5ui';

  let files = $state<File[]>([]);
  let api = $state<ImageCropperApi>();

  const file = $derived(files[0] ?? null);

  // src takes a string, a File or a Blob. A File or Blob is turned into an
  // object URL internally, and that URL is revoked when src changes or the
  // component is destroyed, so there is nothing to clean up here.
  async function save() {
    const result = await api?.crop();
    if (!result) return;

    const body = new FormData();
    body.append('avatar', result.file);
    await fetch('/api/avatar', { method: 'POST', body });
  }
</script>

<FileUpload accept="image/*" bind:value={files} />

<ImageCropper bind:api src={file} shape="circle" size="lg" />

<Button label="Upload" onclick={save} disabled={!file} />

<script lang="ts">
  import { ImageCropper } from 'sv5ui';

  let zoom = $state(1);
</script>

<!-- zoom is bindable: 1 fits the image to the frame, and an assignment from
     the outside is clamped into [minZoom, maxZoom] rather than rejected. -->
<ImageCropper
  bind:zoom
  src={photo}
  minZoom={1}
  maxZoom={5}
  zoomStep={0.1}
/>

<p>{zoom.toFixed(2)}x</p>

<!-- zoomSlider={false} keeps the toolbar buttons and the wheel, and drops
     only the slider under the stage. -->
<ImageCropper src={photo} zoomSlider={false} />

<!-- Double clicking the stage toggles between the minimum zoom and 2x,
     centred on the pointer. -->

<!-- 'always' (default): the wheel zooms and the page does not scroll while
     the pointer is over the stage. Best when the cropper owns the screen,
     for example inside a modal. -->
<ImageCropper src={photo} wheelZoom="always" />

<!-- 'ctrl': the wheel zooms only while Ctrl or Cmd is held, and scrolls the
     page otherwise. Use this for a cropper sitting in a long form, where
     trapping the wheel would strand the reader. -->
<ImageCropper src={photo} wheelZoom="ctrl" />

<!-- false: the wheel never zooms. The slider, the toolbar and the keyboard
     still do. -->
<ImageCropper src={photo} wheelZoom={false} />

<script lang="ts">
  import { ImageCropper, Button, type ImageCropperApi } from 'sv5ui';

  let api = $state<ImageCropperApi>();
  let rotation = $state(0);
  let flipX = $state(false);
  let flipY = $state(false);
</script>

<!-- rotation, flipX and flipY are all bindable, so the current transform can
     be read, stored and restored. -->
<ImageCropper
  bind:api
  bind:rotation
  bind:flipX
  bind:flipY
  src={photo}
  rotationSlider
/>

<!-- The toolbar rotates in quarter turns. The api reaches any angle. -->
<Button label="Straighten" onclick={() => api?.rotateTo(0)} />
<Button label="-1 degree" onclick={() => api?.rotate(-1)} />
<Button label="Mirror" onclick={() => api?.flip('horizontal')} />

<!-- Free angles are exact in fixed mode. In box mode the frame is bounded by
     the rotated image's bounding box, so a frame pushed into a corner can
     pick up transparent pixels: prefer quarter turns there. -->

<!-- grid draws the rule-of-thirds guides inside the frame. -->
<ImageCropper src={photo} grid />

<!-- padding is the gap in pixels between the stage edge and the frame, so a
     larger value leaves more of the image visible around the crop. -->
<ImageCropper src={photo} padding={32} />

<!-- minCropSize is the smallest frame the handles can produce, in pixels on
     screen. It only applies to box mode, which is the only mode with
     handles. -->
<ImageCropper src={photo} mode="box" aspect="free" minCropSize={96} />

<!-- true (default) renders all seven buttons in this order:
     zoomOut, zoomIn, rotateLeft, rotateRight, flipHorizontal,
     flipVertical, reset -->
<ImageCropper src={photo} toolbar />

<!-- An array picks the buttons and their order. -->
<ImageCropper src={photo} toolbar={['rotateLeft', 'rotateRight', 'reset']} />

<!-- false removes the toolbar. The keyboard shortcuts still work. -->
<ImageCropper src={photo} toolbar={false} />

<!-- Swap individual icons without touching the layout. -->
<ImageCropper
  src={photo}
  icons={{ reset: 'lucide:undo-2', rotateLeft: 'lucide:corner-up-left' }}
/>

<script lang="ts">
  import { ImageCropper, Button, Badge } from 'sv5ui';

  let ratio = $state(1);
</script>

<ImageCropper src={photo} aspect={ratio} zoomSlider={false}>
  <!-- toolbarSlot replaces the default toolbar entirely and receives the
       same api you would get from bind:api -->
  {#snippet toolbarSlot({ api })}
    <div class="flex gap-2">
      <Button size="sm" label="1:1" onclick={() => (ratio = 1)} />
      <Button size="sm" label="16:9" onclick={() => (ratio = 16 / 9)} />
      <Button size="sm" label="Rotate" onclick={() => api.rotate(90)} />
      <Button size="sm" variant="ghost" label="Reset" onclick={api.reset} />
    </div>
  {/snippet}

  <!-- footer sits under the stage, after the zoom slider -->
  {#snippet footer({ api })}
    <Badge label={`${Math.round(api.area.width)} x ${Math.round(api.area.height)} px`} />
  {/snippet}
</ImageCropper>

<script lang="ts">
  import { ImageCropper, type ImageCropperApi } from 'sv5ui';

  let api = $state<ImageCropperApi>();

  async function inspect() {
    const result = await api?.crop();
    if (!result) return;
    // width and height are the exported pixels, area is the region in
    // source-image pixels. They differ as soon as maxWidth or maxHeight
    // downscales the crop.
    console.log(result.width, result.height, result.blob.size);
  }
</script>

<!-- A crop is always rendered at source resolution, not at the size the
     stage happens to be on screen. maxWidth and maxHeight cap that, and
     never upscale beyond the source. -->
<ImageCropper
  bind:api
  src={photo}
  output={{
    type: 'image/jpeg',
    quality: 0.82,
    maxWidth: 512,
    maxHeight: 512
  }}
/>

<!-- The exported File is named after the source when there is one:
     avatar.png becomes avatar-cropped.jpg. Otherwise it is crop.jpg. -->

<script lang="ts">
  import { ImageCropper } from 'sv5ui';

  let preview = $state<string | null>(null);
</script>

<!-- autoCrop crops after every change without waiting for crop(), which is
     what a live preview wants. true debounces at 300ms; a number sets the
     delay. Encoding runs on every settled change, so keep the delay high
     enough that a drag does not encode a large image on every frame. -->
<ImageCropper
  src={photo}
  autoCrop={500}
  onCrop={(result) => (preview = URL.createObjectURL(result.blob))}
/>

{#if preview}
  <img src={preview} alt="Live preview" class="size-24 rounded-full" />
{/if}

<script lang="ts">
  import { ImageCropper, Button, type ImageCropperApi } from 'sv5ui';

  let api = $state<ImageCropperApi>();
  let value = $state<File | null>(null);

  // value holds the File from the most recent successful crop, so the upload
  // handler never has to keep its own copy.
  async function submit() {
    await api?.crop();
    if (!value) return;

    const body = new FormData();
    body.append('cover', value);
    body.append('title', title);
    await fetch('/api/posts', { method: 'POST', body });
  }
</script>

<ImageCropper bind:api bind:value src={photo} aspect={16 / 9} />

<Button label="Publish" onclick={submit} />

<!-- A File cannot travel through a hidden input, so this component does not
     take part in native form submission. Read bind:value and attach it to
     the payload yourself, the way the handler above does. -->

<script lang="ts">
  import { ImageCropper } from 'sv5ui';

  // area is the crop region in source-image pixels, and it is two-way.
  // The component writes the current region into it, and assigning a region
  // recomputes zoom, pan and the frame to match. Persist it and the user
  // reopens exactly the crop they left.
  let crop = $state(photo.crop);

  async function save() {
    await fetch(`/api/photos/${photo.id}`, {
      method: 'PATCH',
      body: JSON.stringify({ crop })
    });
  }
</script>

<ImageCropper src={photo.url} bind:area={crop} />

<p>x {crop.x}, y {crop.y}, {crop.width} x {crop.height}</p>

<!-- Storing the area rather than the cropped file keeps the original intact,
     lets the crop be re-edited later, and means a change of output format
     costs nothing. With a rotated image the area is the axis-aligned
     bounding box of the rotated region, and restoring goes through that same
     box. -->

<ImageCropper
  src={photo}
  onLoad={({ width, height }) => console.log('decoded', width, height)}
  onAreaChange={(area) => (draft = area)}
  onCropStart={() => (dragging = true)}
  onCropEnd={() => (dragging = false)}
  onCrop={(result) => upload(result.file)}
  onError={(error) => toast.add({ title: error.message, color: 'error' })}
/>

<!-- onCropStart and onCropEnd bracket pointer gestures only: a drag or a
     pinch. Toolbar buttons, the sliders and the keyboard change the area
     without firing them, so use onAreaChange when you need every change and
     the start/end pair only when you need to know a gesture is in flight. -->

<script lang="ts">
  import { ImageCropper, Icon } from 'sv5ui';
</script>

<!-- The placeholder snippet covers the three states the stage can be in
     without a croppable image. Without it, the component renders its own
     icon and label for each. -->
<ImageCropper src={source}>
  {#snippet placeholder({ status })}
    {#if status === 'empty'}
      <Icon name="lucide:image-plus" class="size-8" />
      <p>Choose an image to start cropping</p>
    {:else if status === 'loading'}
      <Icon name="lucide:loader-circle" class="size-8 animate-spin" />
      <p>Fetching the original</p>
    {:else}
      <Icon name="lucide:unplug" class="size-8" />
      <p>That image could not be loaded. Check the link and try again.</p>
    {/if}
  {/snippet}
</ImageCropper>

<!-- Text only, no markup: labels replaces the default strings, which is also
     where translations go. -->
<ImageCropper
  src={source}
  labels={{
    empty: 'Chua chon anh',
    loading: 'Dang tai anh',
    error: 'Khong tai duoc anh'
  }}
/>

<!-- Cropping means reading pixels back out of an image, and the browser only
     allows that for a same-origin image or one served with CORS. A host that
     sends no Access-Control-Allow-Origin fails in one of two ways. -->

<!-- 1. With the default crossorigin="anonymous" the browser asks for the
        image with CORS, the host does not answer, and the image never loads.
        onError fires with code 'load' and the error placeholder is shown. -->
<ImageCropper
  src="https://cdn.example.com/photo.jpg"
  onError={(error) => {
    if (error.code === 'load') {
      toast.add({ title: 'That image host does not allow cropping' });
    }
  }}
/>

<!-- 2. With crossorigin={null} the image is fetched like any other picture
        and displays fine, but the canvas it is drawn into is tainted, so
        crop() resolves to null and onError reports 'tainted'. Nothing is
        thrown either way. -->
<ImageCropper src={url} crossorigin={null} onError={handleError} />

<!-- A host that needs the session cookie, answering with
     Access-Control-Allow-Credentials: true -->
<ImageCropper src={url} crossorigin="use-credentials" />

<!-- The fix is always on the server. When you do not control it, upload
     through your own origin first, or crop the File the user picked, which
     is same-origin by construction. -->
<ImageCropper src={pickedFile} />

<script lang="ts">
  import { Form, FormField, ImageCropper, Button, type ImageCropperApi } from 'sv5ui';
  import { z } from 'zod';

  const schema = z.object({
    avatar: z.instanceof(File, { message: 'Crop your photo before saving' })
  });

  let api = $state<ImageCropperApi>();

  // Form state is a Partial of the schema, so the field starts out absent
  // rather than null. onCrop writes the File into it; bind:value is the
  // alternative when the file also has to live outside the form.
  let state = $state<{ avatar?: File }>({});

  async function onsubmit() {
    // ...
  }
</script>

<Form {schema} bind:state {onsubmit}>
  <FormField label="Avatar" name="avatar" help="Drag to reposition, scroll to zoom">
    <!-- Inside a FormField the cropper inherits size, and switches its color
         to error while the field is failing. A successful crop() writes
         bind:value and emits the field's change event, so the error clears
         the moment the user crops. -->
    <ImageCropper
      bind:api
      src={file}
      shape="circle"
      onCrop={(result) => (state.avatar = result.file)}
    />
  </FormField>

  <Button label="Crop" onclick={() => api?.crop()} />
  <Button type="submit" label="Save" />
</Form>

<!-- color drives the focus ring and the resize handles, not the image -->
<ImageCropper src={photo} color="success" />

<!-- size sets the stage height and the control sizes:
     xs 14rem, sm 16rem, md 18rem, lg 20rem, xl 24rem -->
<ImageCropper src={photo} size="xl" />

<!-- disabled dims the stage and drops every interaction -->
<ImageCropper src={photo} disabled />

<!-- ui reaches each of the sixteen slots -->
<ImageCropper
  src={photo}
  ui={{
    stage: 'rounded-3xl border-2',
    frame: 'outline-2 outline-primary',
    toolbar: 'mx-auto'
  }}
/>

import { defineConfig } from 'sv5ui';

defineConfig({
  imageCropper: {
    defaultVariants: { color: 'secondary', size: 'lg' },
    slots: { stage: 'rounded-2xl' }
  }
});