docs: add focusObjects prop for customizing object-based focus selections

Author: ahnv

README.md

@@ -130,6 +130,7 @@ export default ImageEditor;
 | `signer` | `Signer` | ❌ | Function to generate signed URLs for private images |
 | `onAddImage` | `() => void` | ❌ | Callback function for adding new images |
 | `exportOptions` | `ExportOptions` | ❌ | Configuration for export functionality |
+| `focusObjects` | `string[]` | ❌ | Custom list of selectable focus objects for object-based focus |
 
 ### ImageKitEditor Ref Methods
 
@@ -181,6 +182,19 @@ exportOptions={{
 }}
 ```
 
+### Focus Objects
+
+You can override the list of selectable focus objects used when a transformation's focus is set to "Object" (e.g., Maintain Aspect Ratio, Forced Crop, Extract). If not provided, the editor defaults to ImageKit's supported objects (e.g., person, bicycle, car, dog, etc.).
+
+See the supported object list in the ImageKit docs: https://imagekit.io/docs/image-resize-and-crop#supported-object-list
+
+```tsx
+<ImageKitEditor
+  focusObjects={["person", "cat", "car", "customObject"]}
+  // ... other props
+/>
+```
+
 ### File Element Interface
 
 For advanced use cases with metadata and signed URLs:

packages/imagekit-editor-dev/src/ImageKitEditor.tsx

@@ -7,6 +7,7 @@ import type { HeaderProps } from "./components/header"
 import type { DEFAULT_FOCUS_OBJECTS } from "./schema"
 import {
   type FileElement,
+  type FocusObjects,
   type RequiredMetadata,
   type Signer,
   useEditorStore,
@@ -25,9 +26,7 @@ interface EditorProps<Metadata extends RequiredMetadata = RequiredMetadata> {
   signer?: Signer<Metadata>
   onAddImage?: () => void
   exportOptions?: HeaderProps["exportOptions"]
-  focusObjects?: ReadonlyArray<
-    (typeof DEFAULT_FOCUS_OBJECTS)[number] | (string & {})
-  >
+  focusObjects?: ReadonlyArray<FocusObjects>
   onClose: (args: { dirty: boolean; destroy: () => void }) => void
 }
 

packages/imagekit-editor-dev/src/store.ts

@@ -58,6 +58,10 @@ interface InternalState {
     | null
 }
 
+export type FocusObjects =
+  | (typeof DEFAULT_FOCUS_OBJECTS)[number]
+  | (string & {})
+
 export interface EditorState<
   Metadata extends RequiredMetadata = RequiredMetadata,
 > {
@@ -72,9 +76,7 @@ export interface EditorState<
   signingAbortControllers: Record<string, AbortController>
   signedUrlCache: Record<string, string>
   currentTransformKey: string
-  focusObjects?: ReadonlyArray<
-    (typeof DEFAULT_FOCUS_OBJECTS)[number] | (string & {})
-  >
+  focusObjects?: ReadonlyArray<FocusObjects>
   _internalState: InternalState
 }
 
@@ -84,9 +86,7 @@ export type EditorActions<
   initialize: (initialData?: {
     imageList?: Array<string | FileElement<Metadata>>
     signer?: Signer<Metadata>
-    focusObjects?: ReadonlyArray<
-      (typeof DEFAULT_FOCUS_OBJECTS)[number] | (string & {})
-    >
+    focusObjects?: ReadonlyArray<FocusObjects>
   }) => void
   destroy: () => void
   setCurrentImage: (imageSrc: string | undefined) => void