How to prevent small images from scaling up while keeping large images scaled to fit the longer side?

[cvpv]

Hi everyone, I'm struggling with my cropper configuration and would really appreciate some guidance.

My requirements:

• Fixed cropper container: 400px × 400px
• Circle stencil with 1:1 aspect ratio (square bounding box)
• Stencil size: fixed, default matches the shorter side of the image
• image-restriction: 'stencil'

My current code:

<script setup lang="ts">
import { ref } from "vue";
import { Cropper, CircleStencil } from "vue-advanced-cropper";
import "vue-advanced-cropper/dist/style.css";

interface Props {
  src: string;
}

interface Emits {
  (e: "change", canvas: HTMLCanvasElement | undefined): void;
}

const props = defineProps<Props>();
const emit = defineEmits<Emits>();

const cropperRef = ref<InstanceType<typeof Cropper>>();

const handleChange = () => {
  const result = cropperRef.value?.getResult();
  emit("change", result?.canvas);
};

const stencilSize = ({ boundaries }) => {
  return {
    width: Math.min(boundaries.width, boundaries.height),
    height: Math.min(boundaries.width, boundaries.height),
  };
};

const defaultSize = ({ imageSize }) => {
  return {
    width: imageSize.width,
    height: imageSize.height,
  };
};

defineExpose({
  getResult: () => cropperRef.value?.getResult(),
});
</script>

<template>
  <div class="h-full w-full">
    <Cropper
      ref="cropperRef"
      :src="props.src"
      :stencil-props="{
        handlers: {},
        movable: false,
        resizable: false,
      }"
      :stencil-size="stencilSize"
      :default-size="defaultSize"
      :canvas="{
        width: 200,
        height: 200,
      }"
      image-restriction="stencil"
      class="cropper h-full w-full"
      :stencil-component="CircleStencil"
    />
  </div>
</template>

this is a very small image (much smaller than the 400px container). Currently, it gets automatically scaled up to fill the boundaries (similar to CSS background-size: cover), as shown below:

I want the small image to maintain its original size without being scaled up. The image should appear at its native resolution (1:1 pixel ratio) within the fixed container, like this:

As shown in the screenshot above, after uploading an image: The image should NOT automatically scale up The stencil should automatically scale with 1:1 aspect ratio to match the image's shorter side The stencil should be restricted from moving outside the image boundaries

Current behavior:

• Small images: Automatically scaled up to fit (behaves like CSS background-size: cover) - the shorter side fills the boundaries completely
• Large images: Automatically scaled down - the shorter side fits the boundaries completely

Expected behavior:

• Small images: Should NOT be scaled up, keep original size (1:1 pixel ratio)
• Large images: Should be scaled down so the longer side fits the boundaries completely (not the shorter side)

I've read through the docs but I'm not sure which approach would work best here. Should I customize defaultVisibleArea, defaultBoundaries, or maybe the initStretcher algorithm? Any help or guidance would be greatly appreciated. Thanks in advance!

---

Chinese

大家好，我在配置裁剪器时遇到了一些困难，希望能得到一些指导。

我的需求:

• 固定裁剪器容器: 400px × 400px
• 圆形裁剪框，1:1 宽高比(正方形边界框)
• 裁剪框尺寸: 固定，默认匹配图片短边
• image-restriction: 'stencil'

我当前的代码:

<script setup lang="ts">
import { ref } from "vue";
import { Cropper, CircleStencil } from "vue-advanced-cropper";
import "vue-advanced-cropper/dist/style.css";

interface Props {
  src: string;
}

interface Emits {
  (e: "change", canvas: HTMLCanvasElement | undefined): void;
}

const props = defineProps<Props>();
const emit = defineEmits<Emits>();

const cropperRef = ref<InstanceType<typeof Cropper>>();

const handleChange = () => {
  const result = cropperRef.value?.getResult();
  emit("change", result?.canvas);
};

const stencilSize = ({ boundaries }) => {
  return {
    width: Math.min(boundaries.width, boundaries.height),
    height: Math.min(boundaries.width, boundaries.height),
  };
};

const defaultSize = ({ imageSize }) => {
  return {
    width: imageSize.width,
    height: imageSize.height,
  };
};

defineExpose({
  getResult: () => cropperRef.value?.getResult(),
});
</script>

<template>
  <div class="h-full w-full">
    <Cropper
      ref="cropperRef"
      :src="props.src"
      :stencil-props="{
        handlers: {},
        movable: false,
        resizable: false,
      }"
      :stencil-size="stencilSize"
      :default-size="defaultSize"
      :canvas="{
        width: 200,
        height: 200,
      }"
      image-restriction="stencil"
      class="cropper h-full w-full"
      :stencil-component="CircleStencil"
    />
  </div>
</template>

当前行为:

• 小图片: 自动放大以适配(表现类似 CSS background-size: cover) - 短边完全填充边界
• 大图片: 自动缩小 - 短边完全适配边界

期望行为:

• 小图片: 不应该被放大，保持原始尺寸(1:1 像素比例)
• 大图片: 应该缩小到长边完全适配边界(而不是短边)

我已经阅读了文档，但不太确定哪种方法最合适。我应该自定义 defaultVisibleArea、defaultBoundaries，还是 initStretcher 算法？非常感谢任何帮助和指导！

[shiroringo]

image-restriction="stencil"改成 fit-area 试试呢？ stencil 会随意缩放。

这个文档也折磨了我好久……先试参数，方法没示例完全不知道咋用，能不用的话还是别用了……

[cvpv]

image-restriction="stencil"改成 fit-area 试试呢？ stencil 会随意缩放。

这个文档也折磨了我好久……先试参数，方法没示例完全不知道咋用，能不用的话还是别用了……

我妥协了，下面是我最终的代码：

<script setup lang="ts">
import { ref } from "vue";
import { Cropper, CircleStencil } from "vue-advanced-cropper";
import "vue-advanced-cropper/dist/style.css";

interface Props {
  src: string;
}

interface Emits {
  (e: "change", canvas: HTMLCanvasElement | undefined): void;
}

const props = defineProps<Props>();
const emit = defineEmits<Emits>();

const cropperRef = ref<InstanceType<typeof Cropper>>();

const handleChange = () => {
  const result = cropperRef.value?.getResult();
  emit("change", result?.canvas);
};

const stencilSize = ({ boundaries }) => {
  return {
    width: Math.min(boundaries.width, boundaries.height),
    height: Math.min(boundaries.width, boundaries.height),
  };
};

const defaultSize = ({ imageSize }) => {
  return {
    width: imageSize.width,
    height: imageSize.height,
  };
};

const zoom = (factor: number) => {
  cropperRef.value?.zoom(factor);
};

const rotate = (angle: number) => {
  cropperRef.value?.rotate(angle);
};

defineExpose({
  getResult: () => cropperRef.value?.getResult(),
  zoom,
  rotate,
});
</script>

<template>
  <div class="h-full w-full">
    <Cropper
      ref="cropperRef"
      :src="props.src"
      :stencil-props="{
        handlers: {},
        movable: false,
        resizable: false,
      }"
      :stencil-size="stencilSize"
      :default-size="defaultSize"
      :canvas="{
        width: 200,
        height: 200,
      }"
      image-restriction="stencil"
      class="cropper h-full w-full"
      backgroundClass="mosaic-background"
      :stencil-component="CircleStencil"
      @change="handleChange"
    />
  </div>
</template>

<style scoped>
.mosaic-background {
  background-color: transparent !important;
  background-image: repeating-conic-gradient(
    rgb(204 204 204) 0deg,
    rgb(204 204 204) 25%,
    rgb(255 255 255) 0deg,
    rgb(255 255 255) 50%
  ) !important;
}
</style>