API Reference

HqCropper

Creates a new cropper instance.

function HqCropper(
    onSubmit: SubmitHandler,
    config?: Partial<ConfigurationOptions>,
    css?: Partial<ClassNames>,
    onError?: ErrorHandler
): HqCropperInstance

Parameters

onSubmit

Type: (base64: string, blob: Blob | null, state: ApplicationState) => void

Called when user applies the crop. Receives:

• base64 — Cropped image as base64 data URL
• blob — Cropped image as Blob (for uploading)
• state — Current state including original filename

const cropper = HqCropper((base64, blob, state) => {
    // Display preview
    img.src = base64

    // Upload to server
    const formData = new FormData()
    formData.append('avatar', blob, state.fileName)
    fetch('/upload', { method: 'POST', body: formData })
})

config

Type: Partial<ConfigurationOptions>

Optional configuration object. See Configuration for all options.

const cropper = HqCropper(onSubmit, {
    outputSize: 512,
    type: 'png',
})

css

Type: Partial<ClassNames>

Optional CSS class overrides. See Custom Styling for details.

const cropper = HqCropper(
    onSubmit,
    {},
    {
        applyButton: ['btn', 'btn-primary'],
    }
)

onError

Type: (message: string) => void

Optional error handler. Called on validation or processing errors.

const cropper = HqCropper(
    onSubmit,
    { maxFileSize: 5 * 1024 * 1024 },
    undefined,
    (error) => alert(error)
)

Returns

HqCropperInstance

interface HqCropperInstance {
    open: () => void
}

open()

Opens the file picker dialog. When user selects an image, the cropper modal appears.

const cropper = HqCropper(onSubmit)

button.addEventListener('click', () => {
    cropper.open()
})

ConfigurationOptions

Configuration options interface.

interface ConfigurationOptions {
    portalSize: number
    minPortalSize: number
    portalPosition: [number, number] | 'center'
    framePadding: number
    outputSize: number
    compression: number
    type: 'jpeg' | 'png'
    maxFileSize: number
    allowedTypes: string[]
    applyButtonLabel: string
    cancelButtonLabel: string
}

Default Values

{
    portalSize: 150,
    minPortalSize: 50,
    portalPosition: 'center',
    framePadding: 3,
    outputSize: 0,
    compression: 1,
    type: 'jpeg',
    maxFileSize: 0,
    allowedTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp'],
    applyButtonLabel: 'Apply',
    cancelButtonLabel: 'Cancel',
}

ApplicationState

State object passed to onSubmit callback.

interface ApplicationState {
    fileName: string
    sourceBase64: string
    sourceWidth: number
    sourceHeight: number
    // ... internal properties
}

Useful Properties

• fileName — Original file name (e.g., "photo.jpg")
• sourceWidth — Original image width
• sourceHeight — Original image height