react-native-customizable-image-crop-picker 1.0.1

package/package.json

@@ -0,0 +1,116 @@
+{
+  "name": "react-native-customizable-image-crop-picker",
+  "version": "1.0.1",
+  "description": "Fully customizable React Native image crop picker (JS UI + native performance).",
+  "keywords": [
+    "react-native",
+    "image",
+    "picker",
+    "crop",
+    "cropper",
+    "camera",
+    "gallery",
+    "typescript"
+  ],
+  "homepage": "https://github.com/amitkumarcoding/imagecroppicker/blob/main/packages/react-native-customizable-image-crop-picker/README.md",
+  "bugs": {
+    "url": "https://github.com/amitkumarcoding/imagecroppicker/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/amitkumarcoding/imagecroppicker.git#main"
+  },
+  "license": "MIT",
+  "author": "Amit Kumar",
+  "type": "commonjs",
+  "exports": {
+    ".": {
+      "react-native": "./src/index.ts",
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/module/index.js",
+      "require": "./dist/commonjs/index.js"
+    }
+  },
+  "main": "dist/commonjs/index.js",
+  "types": "dist/types/index.d.ts",
+  "directories": {
+    "example": "example"
+  },
+  "files": [
+    "android",
+    "assets",
+    "ios",
+    "src",
+    "dist",
+    "*.podspec",
+    "react-native.config.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "npm run clean && bob build",
+    "lint": "eslint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "balanced-match": "^4.0.3",
+    "brace-expansion": "^5.0.2",
+    "glob": "^13.0.6",
+    "minimatch": "^10.2.2"
+  },
+  "devDependencies": {
+    "@react-native/babel-preset": "^0.84.0",
+    "@react-native/eslint-config": "^0.84.0",
+    "@react-native/typescript-config": "^0.84.0",
+    "@types/react": "^19.2.0",
+    "eslint": "^8.57.0",
+    "prettier": "^3.3.3",
+    "react": "^19.2.0",
+    "react-native": "^0.84.0",
+    "react-native-builder-bob": "^0.40.1",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "react-native": ">=0.72"
+  },
+  "peerDependenciesMeta": {
+    "react-native-safe-area-context": {
+      "optional": true
+    },
+    "react-native-svg": {
+      "optional": true
+    }
+  },
+  "sideEffects": false,
+  "module": "dist/module/index.js",
+  "react-native": "src/index.ts",
+  "source": "src/index.ts",
+  "bob": {
+    "source": "src",
+    "output": "dist",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.json"
+        }
+      ]
+    ]
+  },
+  "eslintConfig": {
+    "root": true,
+    "extends": [
+      "@react-native",
+      "prettier"
+    ]
+  },
+  "prettier": {
+    "singleQuote": true,
+    "trailingComma": "all"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,13 @@
+module.exports = {
+  dependency: {
+    platforms: {
+      android: {
+        sourceDir: './android',
+        packageImportPath:
+          'import com.rncustomizableimagecroppicker.NativeImageCropperPackage;',
+        packageInstance: 'new NativeImageCropperPackage()',
+      },
+    },
+  },
+};
+

package/src/api.ts

@@ -0,0 +1,41 @@
+import { normalizeNativeError } from './errors';
+import type { CropResult, OpenOptions } from './types';
+import { NativeImageCropperModule } from './native/NativeImageCropperModule';
+import { mapOpenOptionsToNative } from './native/mapOptions';
+import { NativeEventEmitter, Platform } from 'react-native';
+
+export async function openImageCropPicker(options: OpenOptions): Promise<CropResult> {
+  options.onCropStart?.();
+  options.onProgress?.(0);
+  const emitter =
+    Platform.OS === 'android' ? new NativeEventEmitter(NativeImageCropperModule as any) : null;
+  const sub =
+    options.onProgress && emitter
+      ? emitter.addListener('NativeImageCropperProgress', (evt: any) => {
+          const p = typeof evt?.progress === 'number' ? evt.progress : undefined;
+          if (typeof p === 'number') options.onProgress?.(Math.max(0, Math.min(1, p)));
+        })
+      : null;
+  try {
+    const nativeOptions = mapOpenOptionsToNative(options);
+    const result = await NativeImageCropperModule.openImagePreview(nativeOptions);
+    const path = result.path ?? '';
+    if (!path) {
+      throw new Error('Native cropper returned empty path');
+    }
+    const payload = { path, base64: options.includeBase64 ? result.base64 : undefined };
+    options.onProgress?.(1);
+    options.onCropEnd?.(payload, undefined);
+    return payload;
+  } catch (e) {
+    const err = normalizeNativeError(e);
+    options.onCropEnd?.(undefined, err);
+    throw err;
+  } finally {
+    sub?.remove();
+  }
+}
+
+// Backwards compatible alias.
+export const open = openImageCropPicker;
+

package/src/errors.ts

@@ -0,0 +1,39 @@
+export type CropPickerErrorCode =
+  | 'E_ACTIVITY_DOES_NOT_EXIST'
+  | 'E_PICKER_CANCELLED'
+  | 'E_NO_IMAGE_DATA_FOUND'
+  | 'E_MODULE_DESTROYED'
+  | 'E_PICKER_ERROR'
+  | 'E_PERMISSION_MISSING'
+  | 'E_NO_APP_AVAILABLE'
+  | 'E_UNAVAILABLE'
+  | 'E_INVALID_OPTIONS';
+
+export class CropPickerError extends Error {
+  code: CropPickerErrorCode;
+  details?: unknown;
+
+  constructor(code: CropPickerErrorCode, message: string, details?: unknown) {
+    super(message);
+    this.name = 'CropPickerError';
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export function normalizeNativeError(error: unknown): CropPickerError {
+  if (error instanceof CropPickerError) return error;
+
+  const anyErr = error as any;
+  const code =
+    (typeof anyErr?.code === 'string' ? anyErr.code : undefined) ??
+    (typeof anyErr?.nativeErrorCode === 'string' ? anyErr.nativeErrorCode : undefined) ??
+    'E_PICKER_ERROR';
+
+  const message =
+    (typeof anyErr?.message === 'string' && anyErr.message) ||
+    'Image picker failed';
+
+  return new CropPickerError(code as CropPickerErrorCode, message, error);
+}
+

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './types';
+export * from './errors';
+export * from './api';
+export { ImageCropPickerModal } from './ui/ImageCropPickerModal';

package/src/native/NativeImageCropperModule.ts

@@ -0,0 +1,34 @@
+import { NativeModules, Platform } from 'react-native';
+
+export type NativeOpenImagePreviewOptions = Record<string, unknown>;
+
+export type NativeOpenImagePreviewResult = {
+  path?: string;
+  base64?: string;
+};
+
+type NativeModuleShape = {
+  openImagePreview(
+    options: NativeOpenImagePreviewOptions,
+  ): Promise<NativeOpenImagePreviewResult>;
+};
+
+const LINKING_ERROR =
+  `The package "react-native-customizable-image-crop-picker" doesn't seem to be linked. ` +
+  Platform.select({
+    ios: "Make sure you have run 'pod install'. ",
+    default: '',
+  }) +
+  'Make sure you rebuilt the app after installing the package.';
+
+export const NativeImageCropperModule: NativeModuleShape =
+  NativeModules.NativeImageCropperModule ??
+  new Proxy(
+    {},
+    {
+      get() {
+        throw new Error(LINKING_ERROR);
+      },
+    },
+  ) as NativeModuleShape;
+

package/src/native/mapOptions.ts

@@ -0,0 +1,164 @@
+import type { OpenOptions } from '../types';
+import { Image, StyleSheet } from 'react-native';
+
+export function mapOpenOptionsToNative(options: OpenOptions): Record<string, unknown> {
+  const cropWidth = options.cropWidth ?? options.aspectRatio?.width;
+  const cropHeight = options.cropHeight ?? options.aspectRatio?.height;
+
+  const headerTitle = options.headerTitle ?? 'Preview Image';
+  const cancelText = options.cancelText ?? 'Cancel';
+  const uploadText = options.uploadText ?? 'Upload';
+
+  const headerStyle = options.headerStyle;
+  const footerStyle = options.footerStyle;
+
+  const resolveIconUri = (
+    input: unknown,
+  ): string | undefined => {
+    if (typeof input === 'string') return input;
+    if (input == null) return undefined;
+    // Accept RN assets (require()) and resolve to a URI string.
+    const resolved = Image.resolveAssetSource(input as any);
+    return resolved?.uri;
+  };
+
+  const headerStylePayload: Record<string, unknown> = {};
+  if (headerStyle) {
+    headerStylePayload.backgroundColor = (headerStyle.containerStyle as any)?.backgroundColor;
+    headerStylePayload.color = (headerStyle.titleStyle as any)?.color;
+    headerStylePayload.fontSize = (headerStyle.titleStyle as any)?.fontSize;
+    headerStylePayload.fontFamily = (headerStyle.titleStyle as any)?.fontFamily;
+  }
+  if (options.headerHeight != null) headerStylePayload.height = options.headerHeight;
+  if (options.headerPaddingHorizontal != null)
+    headerStylePayload.paddingHorizontal = options.headerPaddingHorizontal;
+  if (options.headerPaddingTop != null) headerStylePayload.paddingTop = options.headerPaddingTop;
+  if (options.headerPaddingBottom != null)
+    headerStylePayload.paddingBottom = options.headerPaddingBottom;
+
+  const buttonContainerStylePayload: Record<string, unknown> = {};
+  if (footerStyle) {
+    const footerContainer = StyleSheet.flatten(footerStyle.containerStyle as any);
+    buttonContainerStylePayload.backgroundColor = footerContainer?.backgroundColor;
+    // Allow React Native-like spacing props on the native footer container.
+    if (typeof footerContainer?.paddingHorizontal === 'number')
+      buttonContainerStylePayload.paddingHorizontal = footerContainer.paddingHorizontal;
+    if (typeof footerContainer?.paddingTop === 'number')
+      buttonContainerStylePayload.paddingTop = footerContainer.paddingTop;
+    if (typeof footerContainer?.paddingBottom === 'number')
+      buttonContainerStylePayload.paddingBottom = footerContainer.paddingBottom;
+    if (typeof footerContainer?.gap === 'number') buttonContainerStylePayload.gap = footerContainer.gap;
+  }
+  if (options.footerPaddingHorizontal != null)
+    buttonContainerStylePayload.paddingHorizontal = options.footerPaddingHorizontal;
+  if (options.footerPaddingTop != null)
+    buttonContainerStylePayload.paddingTop = options.footerPaddingTop;
+  if (options.footerPaddingBottom != null)
+    buttonContainerStylePayload.paddingBottom = options.footerPaddingBottom;
+  if (options.footerButtonGap != null) buttonContainerStylePayload.gap = options.footerButtonGap;
+  if (options.footerButtonHeight != null)
+    buttonContainerStylePayload.buttonHeight = options.footerButtonHeight;
+  if (options.footerButtonLayout != null)
+    buttonContainerStylePayload.layout = options.footerButtonLayout;
+
+  const cancelButtonStylePayload: Record<string, unknown> = {};
+  if (footerStyle) {
+    cancelButtonStylePayload.backgroundColor = (footerStyle.cancelButtonStyle as any)?.backgroundColor;
+    cancelButtonStylePayload.borderColor = (footerStyle.cancelButtonStyle as any)?.borderColor;
+    cancelButtonStylePayload.borderWidth = (footerStyle.cancelButtonStyle as any)?.borderWidth;
+    cancelButtonStylePayload.fontFamily = (footerStyle.cancelTextStyle as any)?.fontFamily;
+    cancelButtonStylePayload.fontSize = (footerStyle.cancelTextStyle as any)?.fontSize;
+    cancelButtonStylePayload.textColor = (footerStyle.cancelTextStyle as any)?.color;
+    cancelButtonStylePayload.borderRadius = (footerStyle.cancelButtonStyle as any)?.borderRadius;
+  }
+  if (options.cancelButtonRadius != null && cancelButtonStylePayload.borderRadius == null) {
+    cancelButtonStylePayload.borderRadius = options.cancelButtonRadius;
+  }
+  if (options.cancelButtonContent != null) cancelButtonStylePayload.content = options.cancelButtonContent;
+  const cancelIconUri = resolveIconUri(options.cancelButtonIconUri);
+  if (cancelIconUri != null) cancelButtonStylePayload.iconUri = cancelIconUri;
+  if (options.cancelButtonIconBase64 != null) cancelButtonStylePayload.iconBase64 = options.cancelButtonIconBase64;
+  if (options.cancelButtonIconTintColor != null)
+    cancelButtonStylePayload.iconTintColor = options.cancelButtonIconTintColor;
+  if (options.cancelButtonIconSize != null) cancelButtonStylePayload.iconSize = options.cancelButtonIconSize;
+  if (options.buttonIconGap != null) cancelButtonStylePayload.iconGap = options.buttonIconGap;
+  const cancelPadH =
+    options.cancelButtonContentPaddingHorizontal ?? options.buttonContentPaddingHorizontal;
+  const cancelPadV =
+    options.cancelButtonContentPaddingVertical ?? options.buttonContentPaddingVertical;
+  if (cancelPadH != null) cancelButtonStylePayload.paddingHorizontal = cancelPadH;
+  if (cancelPadV != null) cancelButtonStylePayload.paddingVertical = cancelPadV;
+
+  const uploadButtonStylePayload: Record<string, unknown> = {};
+  if (footerStyle) {
+    uploadButtonStylePayload.backgroundColor = (footerStyle.uploadButtonStyle as any)?.backgroundColor;
+    uploadButtonStylePayload.borderColor = (footerStyle.uploadButtonStyle as any)?.borderColor;
+    uploadButtonStylePayload.borderWidth = (footerStyle.uploadButtonStyle as any)?.borderWidth;
+    uploadButtonStylePayload.fontFamily = (footerStyle.uploadTextStyle as any)?.fontFamily;
+    uploadButtonStylePayload.fontSize = (footerStyle.uploadTextStyle as any)?.fontSize;
+    uploadButtonStylePayload.textColor = (footerStyle.uploadTextStyle as any)?.color;
+    uploadButtonStylePayload.borderRadius = (footerStyle.uploadButtonStyle as any)?.borderRadius;
+  }
+  if (options.uploadButtonRadius != null && uploadButtonStylePayload.borderRadius == null) {
+    uploadButtonStylePayload.borderRadius = options.uploadButtonRadius;
+  }
+  if (options.uploadButtonContent != null) uploadButtonStylePayload.content = options.uploadButtonContent;
+  const uploadIconUri = resolveIconUri(options.uploadButtonIconUri);
+  if (uploadIconUri != null) uploadButtonStylePayload.iconUri = uploadIconUri;
+  if (options.uploadButtonIconBase64 != null) uploadButtonStylePayload.iconBase64 = options.uploadButtonIconBase64;
+  if (options.uploadButtonIconTintColor != null)
+    uploadButtonStylePayload.iconTintColor = options.uploadButtonIconTintColor;
+  if (options.uploadButtonIconSize != null) uploadButtonStylePayload.iconSize = options.uploadButtonIconSize;
+  if (options.buttonIconGap != null) uploadButtonStylePayload.iconGap = options.buttonIconGap;
+  const uploadPadH =
+    options.uploadButtonContentPaddingHorizontal ?? options.buttonContentPaddingHorizontal;
+  const uploadPadV =
+    options.uploadButtonContentPaddingVertical ?? options.buttonContentPaddingVertical;
+  if (uploadPadH != null) uploadButtonStylePayload.paddingHorizontal = uploadPadH;
+  if (uploadPadV != null) uploadButtonStylePayload.paddingVertical = uploadPadV;
+
+  return {
+    pickerSource: options.source,
+    width: typeof cropWidth === 'number' ? Math.round(cropWidth) : undefined,
+    height: typeof cropHeight === 'number' ? Math.round(cropHeight) : undefined,
+    freeStyleCropEnabled: options.freeStyleCropEnabled === true,
+    includeBase64: options.includeBase64 === true,
+    compressQuality:
+      typeof options.compressQuality === 'number' ? options.compressQuality : undefined,
+    compressFormat: options.compressFormat,
+    circularCrop: options.circularCrop === true,
+    rotationEnabled: options.rotationEnabled === true,
+    cropGridEnabled: options.cropGridEnabled === true,
+    cropFrameColor: options.cropFrameColor,
+    cropGridColor: options.cropGridColor,
+    showNativeCropControls: options.showNativeCropControls === true,
+    isDarkTheme: options.isDarkTheme === true,
+    drawUnderStatusBar: options.drawUnderStatusBar === true,
+    cropperStatusBarColor: options.statusBarColor,
+    cropperStatusBarStyle: options.statusBarStyle,
+    cropperDimmedLayerColor:
+      options.dimmedLayerColor ?? options.cropOverlayColor,
+
+    cropperToolbarTitle: headerTitle,
+    cropperCancelText: cancelText,
+    cropperChooseText: uploadText,
+    headerAlignment: options.headerAlignment,
+    controlsPlacement: options.controlsPlacement,
+    topLeftControl: options.topLeftControl,
+    topRightControl: options.topRightControl,
+    footerButtonOrder: options.footerButtonOrder,
+
+    // Best-effort mapping to existing native keys.
+    headerStyle: Object.keys(headerStylePayload).length ? headerStylePayload : undefined,
+    buttonContainerStyle: Object.keys(buttonContainerStylePayload).length
+      ? buttonContainerStylePayload
+      : undefined,
+    cancelButtonStyle: Object.keys(cancelButtonStylePayload).length
+      ? cancelButtonStylePayload
+      : undefined,
+    uploadButtonStyle: Object.keys(uploadButtonStylePayload).length
+      ? uploadButtonStylePayload
+      : undefined,
+  };
+}
+

package/src/types.ts

@@ -0,0 +1,258 @@
+import type * as React from 'react';
+import type {
+  ImageSourcePropType,
+  ImageStyle,
+  StyleProp,
+  TextStyle,
+  ViewStyle,
+} from 'react-native';
+
+export type PickerSource = 'camera' | 'gallery';
+export type HeaderAlignment = 'left' | 'center' | 'right';
+
+export type CropCompressionFormat = 'jpeg' | 'png' | 'webp';
+
+export type CropResult = {
+  path: string;
+  width?: number;
+  height?: number;
+  mime?: string;
+  size?: number;
+  base64?: string;
+  exif?: Record<string, unknown>;
+};
+
+export type PickedImage = {
+  path: string;
+  width?: number;
+  height?: number;
+  mime?: string;
+  size?: number;
+};
+
+export type IconElement = React.ReactNode;
+
+export type HeaderStyle = {
+  containerStyle?: StyleProp<ViewStyle>;
+  titleStyle?: StyleProp<TextStyle>;
+  leftIconContainerStyle?: StyleProp<ViewStyle>;
+  rightIconContainerStyle?: StyleProp<ViewStyle>;
+};
+
+export type FooterStyle = {
+  containerStyle?: StyleProp<ViewStyle>;
+  buttonRowStyle?: StyleProp<ViewStyle>;
+  cancelButtonStyle?: StyleProp<ViewStyle>;
+  uploadButtonStyle?: StyleProp<ViewStyle>;
+  cancelTextStyle?: StyleProp<TextStyle>;
+  uploadTextStyle?: StyleProp<TextStyle>;
+  cancelIconContainerStyle?: StyleProp<ViewStyle>;
+  uploadIconContainerStyle?: StyleProp<ViewStyle>;
+};
+
+export type CropperOverlayStyle = {
+  containerStyle?: StyleProp<ViewStyle>;
+  previewContainerStyle?: StyleProp<ViewStyle>;
+  imageStyle?: StyleProp<ImageStyle>;
+  cropOverlayStyle?: StyleProp<ViewStyle>;
+};
+
+export type CropperUIProps = {
+  showHeader?: boolean;
+  headerTitle?: string;
+  headerAlignment?: HeaderAlignment;
+  leftIcon?: IconElement;
+  rightIcon?: IconElement;
+  showLeftIcon?: boolean;
+  showRightIcon?: boolean;
+  headerStyle?: HeaderStyle;
+  /**
+   * Native-only layout knobs (used by the native full-screen crop UI).
+   * For fully custom React components, use `ImageCropPickerModal`.
+   */
+  headerHeight?: number;
+  headerPaddingHorizontal?: number;
+  headerPaddingTop?: number;
+  headerPaddingBottom?: number;
+  /**
+   * Android native UI only:
+   * - false (default): header starts below the status bar (not "stuck" under it)
+   * - true: draw header under status bar (edge-to-edge)
+   */
+  drawUnderStatusBar?: boolean;
+
+  showFooter?: boolean;
+  cancelText?: string;
+  uploadText?: string;
+  cancelIcon?: IconElement;
+  uploadIcon?: IconElement;
+  footerStyle?: FooterStyle;
+  footerPaddingHorizontal?: number;
+  footerPaddingTop?: number;
+  footerPaddingBottom?: number;
+  footerButtonGap?: number;
+  footerButtonHeight?: number;
+  /**
+   * Native full-screen footer button layout.
+   * - vertical: Upload on top, Cancel below
+   * - horizontal: Cancel left, Upload right
+   */
+  footerButtonLayout?: 'vertical' | 'horizontal';
+  /**
+   * Native full-screen controls placement.
+   * - bottom: render actions in the footer (default)
+   * - top: render actions in the header (title stays centered)
+   */
+  controlsPlacement?: 'bottom' | 'top';
+  /**
+   * Only used when `controlsPlacement: 'top'`.
+   * Decide which control appears on the left/right side.
+   */
+  topLeftControl?: 'cancel' | 'upload' | 'none';
+  topRightControl?: 'cancel' | 'upload' | 'none';
+  /**
+   * Only used when `controlsPlacement: 'bottom'`.
+   * Controls ordering within the footer.
+   * - uploadFirst: Upload then Cancel (default)
+   * - cancelFirst: Cancel then Upload
+   */
+  footerButtonOrder?: 'uploadFirst' | 'cancelFirst';
+
+  /**
+   * Native full-screen: control content mode per button.
+   * - text: label only
+   * - icon: icon only
+   * - iconText | icon+text: icon then label
+   * - textIcon | TextIcon | text+icon: label then icon
+   */
+  cancelButtonContent?:
+    | 'text'
+    | 'icon'
+    | 'iconText'
+    | 'textIcon'
+    | 'TextIcon'
+    | 'icon+text'
+    | 'text+icon';
+  uploadButtonContent?:
+    | 'text'
+    | 'icon'
+    | 'iconText'
+    | 'textIcon'
+    | 'TextIcon'
+    | 'icon+text'
+    | 'text+icon';
+  cancelButtonIconUri?: string | ImageSourcePropType;
+  uploadButtonIconUri?: string | ImageSourcePropType;
+  cancelButtonIconBase64?: string;
+  uploadButtonIconBase64?: string;
+  cancelButtonIconTintColor?: string;
+  uploadButtonIconTintColor?: string;
+  cancelButtonIconSize?: number;
+  uploadButtonIconSize?: number;
+  buttonIconGap?: number;
+
+  /**
+   * Native full-screen: internal content padding for the action buttons.
+   * These apply to both buttons unless you override per-button.
+   */
+  buttonContentPaddingHorizontal?: number;
+  buttonContentPaddingVertical?: number;
+  cancelButtonContentPaddingHorizontal?: number;
+  cancelButtonContentPaddingVertical?: number;
+  uploadButtonContentPaddingHorizontal?: number;
+  uploadButtonContentPaddingVertical?: number;
+  cancelButtonRadius?: number;
+  uploadButtonRadius?: number;
+
+  overlayStyle?: CropperOverlayStyle;
+  backgroundColor?: string;
+  safeAreaEnabled?: boolean;
+
+  /**
+   * Native full-screen UI appearance.
+   */
+  isDarkTheme?: boolean;
+  statusBarColor?: string;
+  /**
+   * Android native UI only: status bar icon/text color.
+   * - dark: dark icons (for light backgrounds)
+   * - light: light icons (for dark backgrounds)
+   */
+  statusBarStyle?: 'dark' | 'light';
+  /**
+   * Native dimmed overlay color around the crop box (Android uses this directly).
+   * Example: "#CC0B1B3A"
+   */
+  dimmedLayerColor?: string;
+
+  /**
+   * Show native crop controls (rotation/aspect ratio toolbar).
+   * - Android: shows uCrop bottom controls and forces actions into the header.
+   * - iOS: shows TOCropViewController toolbar controls.
+   */
+  showNativeCropControls?: boolean;
+};
+
+export type CropOptions = {
+  cropWidth?: number;
+  cropHeight?: number;
+  aspectRatio?: { width: number; height: number };
+  freeStyleCropEnabled?: boolean;
+  circularCrop?: boolean;
+  rotationEnabled?: boolean;
+  cropGridEnabled?: boolean;
+  cropOverlayColor?: string;
+  cropFrameColor?: string;
+  cropGridColor?: string;
+
+  compressQuality?: number; // 0..1
+  compressFormat?: CropCompressionFormat;
+  includeBase64?: boolean;
+};
+
+export type PickerOptions = {
+  source: PickerSource;
+  multiple?: boolean;
+  maxFiles?: number;
+  mediaType?: 'photo';
+};
+
+export type OpenOptions = PickerOptions &
+  CropOptions &
+  CropperUIProps & {
+    /**
+     * If true, use the native full-screen UI flow (if your native layer supports it).
+     * If false, you can render JS chrome and use a native cropper *view* (future step).
+     */
+    preferNativeUI?: boolean;
+
+    /**
+     * JS callbacks (not passed to native).
+     */
+    onCropStart?: () => void;
+    onCropEnd?: (result?: CropResult, error?: unknown) => void;
+    /**
+     * Progress for slow work (currently best-effort; Android emits real base64 progress).
+     * 0..1
+     */
+    onProgress?: (progress: number) => void;
+  };
+
+export type CropperRenderContext = {
+  title: string;
+  headerAlignment: HeaderAlignment;
+  onCancel: () => void;
+  onConfirm: () => void;
+};
+
+export type CropperRenderHeader = (ctx: CropperRenderContext) => React.ReactNode;
+export type CropperRenderFooter = (ctx: CropperRenderContext) => React.ReactNode;
+export type CropperRenderButton = (ctx: CropperRenderContext) => React.ReactNode;
+
+export type CropperRenderOverrides = {
+  renderHeader?: CropperRenderHeader;
+  renderFooter?: CropperRenderFooter;
+  renderCancelButton?: CropperRenderButton;
+  renderUploadButton?: CropperRenderButton;
+};
+