Detects whether an image is predominantly dark or light by sampling pixels via OffscreenCanvas. Uses APCA perceptual lightness (sRGB linearization + power curve) for accurate detection, especially on saturated colors. Runs entirely off the paint path: no visible canvas, no layout thrash. Supports regional sampling for detecting luminance where text overlays will appear. Returns null while loading and falls back gracefully on CORS or network errors.
ts
| Guidance | Practices |
|---|---|
| Do | Pair with MediaTheme to automatically adapt text color over dynamic background images. |
| Do | Use the region option to sample only the area where text overlays will appear for more accurate results. |
| Don't | Use for images that change rapidly (e.g., video frames); each src change triggers a new fetch and analysis. |
| Param | Type | Description |
|---|---|---|
srcrequired | string | null | undefined | Image source URL to analyze. When null/undefined, returns the fallback value. |
options | UseImageModeOptions | Optional configuration for image analysis. |
options.region | ImageSampleRegion | Region to sample within the image using normalized 0-1 coordinates ({ x, y, width, height }). Defaults to the full image. |
options.threshold | number (default: 0.5) | Luminance threshold for the dark/light split. Below = dark, above = light. |
options.fallback | 'dark' | 'light' | null (default: null) | Fallback value while loading or on error. |
| Field | Type | Description |
|---|---|---|
| mode | 'dark' | 'light' | null | Detected luminance mode of the image. Returns null while loading or if src is null/undefined. |