CropModal API
API reference docs for theCropModalwidget. For examples and details on the usage of this widget, visit the widget demo page.
Props
| Props | Type | Description | Default |
|---|---|---|---|
isOpen | boolean | Controls whether the modal is visible. | _ |
imageUrl | string | null | Initial image URL. In online mode, a remote image can be fetched; otherwise users upload locally. | _ |
modalWrapperTranslations | ModalWrapperTranslations | Labels for modal actions and headers. All fields are required. | _ |
modalWrapperTranslations.title | string | Modal header title text. | |
modalWrapperTranslations.subtitle | string | Modal header subtitle/description text. | |
modalWrapperTranslations.saveButtonLabel | string | Text for the save/apply button. | |
modalWrapperTranslations.cancelButtonLabel | string | Text for the cancel button. | |
modalWrapperTranslations.closeModalButtonLabel | string | Accessibility label for the close button (screen readers). | |
cropAreaTranslations? | CropAreaTranslations | These labels populate accessible names and tooltips for controls, and optionally render an "Upload new image" action on non-responsive layouts. | _ |
cropAreaTranslations?.zoomInButtonLabel? | string | Optional label for the zoom-in button. Keep short and descriptive for screen readers (e.g., "Zoom in"). | |
cropAreaTranslations?.zoomOutButtonLabel? | string | Optional label for the zoom-out button. Keep short and descriptive for screen readers (e.g., "Zoom out"). | |
cropAreaTranslations?.uploadNewButtonLabel? | string | Optional label for the action to upload a new image. Rendered in the CropArea only when not in a responsive breakpoint. | |
dropAreaTranslations? | DropAreaTranslations | Labels for file drop area. All fields are required. | _ |
dropAreaTranslations?.uploadImageButtonLabel | string | Text for the upload new file button. | |
dropAreaTranslations?.bottomTextSuffix? | string | Optional text displayed after the link. Completes the inline sentence, e.g., " to continue." | |
dropAreaTranslations?.bottomTextPrefix? | string | Optional text displayed before the link. Useful for sentences like "Drag and drop an image or ". When omitted, nothing is rendered. | |
dropAreaTranslations?.bottomLinkText? | string | Optional text for the helper link (e.g., "browse files"). The link is rendered only when bottomLinkUrl is also provided. | |
dropAreaTranslations?.bottomLinkUrl? | string | Optional absolute URL opened in a new tab when the helper link is clicked. | |
errorTranslations? | ErrorTranslations | Error messages for different scenarios. All fields are optional with default values. | {fileSizeExceedsLimitError: 'This image file is too big. Please upload another.', fileTypeMismatchError: 'The file type is not supported.', fileUploadError: 'An error occurred while uploading the file.', androidFileReadError: 'Image couldn’t be uploaded. Please try again.', fetchIncomingImageError: 'An error occurred while fetching the image.', localFileProcessingError: 'An error occurred while uploading the file.' } |
errorTranslations?.fileSizeExceedsLimitError? | string | Error when file size exceeds limit. | This image file is too big. Please upload another. |
errorTranslations?.fileTypeMismatchError? | string | Error when file type is not allowed. | The file type is not supported. |
errorTranslations?.fileUploadError? | string | Generic processing error message. | An error occurred while uploading the file. |
errorTranslations?.androidFileReadError? | string | Error during upload process. | Image couldn’t be uploaded. Please try again. |
errorTranslations?.fetchIncomingImageError? | string | Network-related error message. | An error occurred while fetching the image. |
errorTranslations?.localFileProcessingError? | string | Error when local file processing fails. | An error occurred while processing the image. |
cropViewBoxOptions? | CropViewBoxOptions | Crop box configuration: width, aspectRatio, and roundingStyle. All fields are optional with default values. | { width: 200, aspectRatio: 1, roundingStyle: "none" } |
cropViewBoxOptions?.width? | number | Width of the crop box in pixels. | 200 |
cropViewBoxOptions?.aspectRatio? | number | Aspect ratio of the crop box (width/height). | 1 |
cropViewBoxOptions?.roundingStyle? | "none" | "rounded" | "circle" | Visual style of the crop box corners. | none |
generalOptions? | GeneralOptions | Canvas sizing and behavior configuration. All fields are optional with default values. | { canvasWidth: 500, canvasHeight: 300, maxScaleFactor: 5, totalSidePadding: 48, saveButtonVariant: "accentPrimary" } |
generalOptions?.canvasWidth? | number | Width of the canvas in pixels. | 500 |
generalOptions?.canvasHeight? | number | Height of the canvas in pixels. | 300 |
generalOptions?.maxScaleFactor? | number | Maximum zoom scale factor for the image. | 5 |
generalOptions?.totalSidePadding? | number | Total padding on sides of the canvas in pixels. | 48 |
generalOptions?.saveButtonVariant? | string | Visual variant for the save button. | accentPrimary |
imageProcessingOptions? | ImageProcessingOptions | Local file validation and optimization configuration. All fields are optional with default values. | { maxWidth: 2560, maxHeight: 2560, enableResize: true, maxFileSizeMB: 5, enableCompression: true, compressionQuality: 0.6, allowedMimeTypes: ["image/png", "image/jpeg", "image/jpg"] } |
imageProcessingOptions.maxWidth? | number | Maximum width for processed images in pixels. | 2560 |
imageProcessingOptions.maxHeight? | number | Maximum height for processed images in pixels. | 2560 |
imageProcessingOptions.enableResize? | boolean | Whether to enable automatic image resizing. | true |
imageProcessingOptions.maxFileSizeMB? | number | Maximum allowed file size in megabytes. | 5 |
imageProcessingOptions.enableCompression? | boolean | Whether to enable image compression. | true |
imageProcessingOptions.compressionQuality? | number | Compression quality (0-1, where 1 is highest quality). | 0.6 |
imageProcessingOptions.allowedMimeTypes? | string[] | Array of allowed MIME types for uploaded files. | ["image/png", "image/jpeg", "image/jpg"] |
apiOptions? | ApiOptions | undefined | Enable online mode: provide uploadUrl, getAccessToken, and helpers to fetch/upload images. When omitted, the widget operates in offline mode using blob URLs only. | |
apiOptions?.uploadUrl | string | URL endpoint for uploading processed images. | |
apiOptions?.getAccessToken | () => Promise<string> | Function that returns an access token for API authentication. | |
apiOptions?.sendFormDataRequest? | (url: string, file: File, formParams: Record<string, string>) => Promise<string> | Function to send form data (e.g., image file) to server and return image URL. | |
apiOptions?.fetchInitialImageUrl? | (url: string) => Promise<Blob>; | Function to fetch initial image URL from server. | |
apiOptions?.fetchGoogleStorageUploadUrl? | (accessToken: string, fileName: string) => Promise<GoogleStorageApiResponse> | Function to fetch Google Storage upload URL from server. | |
onSuccessfulUpload | (url: string, imageData?: ImageData) => void | Called after a successful image upload and client-side processing. | _ |
onClose | () => void | Called when the modal is closed via close button, overlay click, or pressing Esc (when enabled). | _ |
onCancel | () => void | Called when the user clicks the Cancel action in the modal. | _ |
onError? | (error: ErrorDetails) => void | Optional error callback for recoverable failures in the workflow. | _ |