useImageMode
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.
Signature
useImageMode(src: string | null | undefined, options: UseImageModeOptions = {}): 'dark' | 'light' | null| Name | Type and behavior |
|---|---|
src | string | null | undefined · requiredImage source URL to analyze. When null/undefined, returns the fallback value. |
options | UseImageModeOptions · optionalOptional configuration for image analysis. |
options.region | ImageSampleRegion · optionalRegion to sample within the image using normalized 0-1 coordinates ({ x, y, width, height }). Defaults to the full image. |
options.threshold | number · optional · default 0.5Luminance threshold for the dark/light split. Below = dark, above = light. |
options.fallback | 'dark' | 'light' | null · optional · default nullFallback value while loading or on error. |
| Name | Type and behavior |
|---|---|
mode | 'dark' | 'light' | nullDetected luminance mode of the image. Returns null while loading or if src is null/undefined. |
Usage
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.
- Pair with MediaTheme to automatically adapt text color over dynamic background images.
- Use the region option to sample only the area where text overlays will appear for more accurate results.
- Use for images that change rapidly (e.g., video frames); each src change triggers a new fetch and analysis.