UseContrastRegionOptions

interface UseContrastRegionOptions extends ColorPlaneQueryOptions {
  quality?: ColorPlaneQualityLevel;
  isDragging?: boolean;
  performanceProfile?: ColorPlanePerformanceProfile;
  reference?: Color;
  hue?: number;
  gamut?: GamutTarget;
  metric?: ContrastMetric;
  threshold?: number;
  level?: ContrastRegionLevel;
  apcaPreset?: ContrastApcaPreset;
  apcaPolarity?: ContrastApcaPolarity;
  apcaRole?: ContrastApcaRole;
  initialSamples?: number;
  errorTolerance?: number;
  maxDepth?: number;
  maxChroma?: number;
  alpha?: number;
  simplifyTolerance?: number;
  onMetrics?: (metrics: ContrastRegionMetrics) => void;
  includeSchedulerTelemetry?: boolean;
}

Properties

quality?ColorPlaneQualityLeveldefault 'high'

Sampling detail. Pass useAdaptiveQuality's quality to coarsen sampling while frames are slow.

isDragging?booleandefault false

Whether the plane is being dragged. While true, queries run in a shared Web Worker (when available) and the last result stays in place until a fresh one arrives; at rest they run synchronously.

performanceProfile?ColorPlanePerformanceProfiledefault 'auto'

Profile forwarded to the worker's compute scheduler.

reference?Color

Color the region's samples are measured against (gamut-mapped into gamut first). Defaults to the plane color, which is rarely what a text-on-background check wants: pass the fixed background or text color.

hue?number

Hue of the plane slice in degrees. Defaults to the plane color's hue.

gamut?GamutTargetdefault 'srgb'

Gamut the reference and samples are measured in; paths stay inside it.

metric?ContrastMetricdefault 'wcag'

Contrast metric.

threshold?number

Explicit threshold; overrides level and apcaPreset. A WCAG contrast ratio, or with metric: 'apca' a normalized Lc magnitude (0.6 for Lc 60).

level?ContrastRegionLeveldefault 'AA' (4.5:1)

WCAG threshold preset used when threshold is omitted.

apcaPreset?ContrastApcaPresetdefault 'body' (Lc 60, normalized 0.6)

APCA threshold preset used with metric: 'apca' when threshold is omitted.

apcaPolarity?ContrastApcaPolaritydefault 'absolute'

APCA polarity test with metric: 'apca': absolute, positive or negative Lc.

apcaRole?ContrastApcaRoledefault 'sample-text'

Whether samples are the text (sample-text) or the background (sample-background) in APCA.

initialSamples?numberdefault 8

Initial samples per gamut chroma extent, scaled down at lower quality. Tuned for interactive use; see contrastRegionPaths for the solver's own defaults.

errorTolerance?numberdefault 0.004

Largest distance, in l/c units, a sampled midpoint may lie from its chord before the interval is refined.

maxDepth?numberdefault 3 at `high` quality, 2 at `medium`, 1 at `low

Maximum refinement depth per initial interval.

maxChroma?numberdefault 0.4

Upper chroma bound of the region.

alpha?number

Alpha used for the samples while measuring contrast.

simplifyTolerance?number

RDP simplification tolerance in (l, c) space; omit to disable.

onMetrics?(metrics: ContrastRegionMetrics) => void

Called after each sync or worker compute with sampling and timing stats.

includeSchedulerTelemetry?booleandefault false

Include worker scheduler fields in onMetrics.