Add reducedMotionHandling to @wix/interact

CHANGELOG.md

@@ -46,6 +46,13 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact-validate
 
+### [Unreleased]
+
+#### Added
+
+- `reducedMotionHandling` accepted on interactions, sequences and effects, with checks that a named effect exists and is of the same kind (`REDUCED_MOTION_EFFECT_NOT_FOUND`, `REDUCED_MOTION_INCOMPATIBLE_EFFECT`) and the `REDUCED_MOTION` rule category (`REDUCED_MOTION_SELF_REFERENCE`, `REDUCED_MOTION_SHADOWED_EFFECT_ID`, `REDUCED_MOTION_ANIMATION_END_SOURCE_MISMATCH`, `REDUCED_MOTION_COLLAPSE_CANCELS`)
+- An effect named only by a `reducedMotionHandling` is no longer reported as `UNUSED_EFFECT`
+
 ### [0.2.1] - 2026-10-25
 
 #### Added
@@ -112,6 +119,21 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ## @wix/interact
 
+### [Unreleased]
+
+#### Added
+
+- `reducedMotionHandling` on interactions, sequences and effects — `'collapse'` (default), `'ignore'`, `'cancel'` or an effectId — sets what an effect does under `prefers-reduced-motion: reduce`; the most specific level wins. `generate()` emits both outcomes under exclusive `prefers-reduced-motion` media, and the runtime picks the matching one, without adding effects to the config
+- `reducedMotionHandling` and `forceReducedMotion` options for `Interact.setup()` (every instance), `Interact.create()` (one instance) and `generate()` (defaulting to `Interact.setup()`'s)
+
+#### Changed
+
+- **Breaking:** under `prefers-reduced-motion: reduce`, effects collapse by default: they play with duration 0, keeping their delay and iterations, so they jump to their end state. Looping, `viewProgress` and `pointerMove` effects are dropped, and sequence staggers collapse. Pass `reducedMotionHandling: 'ignore'` to `Interact.setup()` to keep the old behavior
+- **Breaking:** `Interact.forceReducedMotion` applies the reduced-motion outcome of `reducedMotionHandling` instead of passing `reducedMotion` to `@wix/motion`. With the default `'collapse'` that matches the old behavior, except that finite multi-iteration animations collapse to their end state instead of being dropped
+- Runtime transitions collapse under `prefers-reduced-motion: reduce` through `reducedMotionHandling`, matching `generate()`, instead of always being wrapped in `prefers-reduced-motion: no-preference`
+- `reducedMotion` removed from `InteractOptions`, and the `context` argument from `Interact.getSequence()` / `Interact.addToSequence()`
+- 0ms transitions that have a delay are kept, so the delay is honored
+
 ### [2.6.0] - 2026-11-02
 
 #### Changed

apps/website/assets/main.mjs

@@ -1739,9 +1739,6 @@ updateTunnelBounds();
 window.addEventListener('resize', buildGrid);
 window.addEventListener('resize', updateTunnelBounds);
 
-// Respect reduced motion settings
-Interact.forceReducedMotion = matchMedia('(prefers-reduced-motion: reduce)').matches;
-
 // Register presets
 Interact.registerEffects(presets);
 

packages/interact-validate/src/errors.ts

@@ -34,6 +34,10 @@ const RULE_CODE_MAP: Record<string, string> = {
   FUNCTION_OFFSET_EASING: 'OFFSET_EASING',
   NAMED_EFFECT_UNKNOWN_PARAM: 'NAMED_EFFECT_PARAMS',
   NAMED_EFFECT_INVALID_PARAM: 'NAMED_EFFECT_PARAMS',
+  REDUCED_MOTION_SELF_REFERENCE: 'REDUCED_MOTION',
+  REDUCED_MOTION_COLLAPSE_CANCELS: 'REDUCED_MOTION',
+  REDUCED_MOTION_ANIMATION_END_SOURCE_MISMATCH: 'REDUCED_MOTION',
+  REDUCED_MOTION_SHADOWED_EFFECT_ID: 'REDUCED_MOTION',
 };
 
 export function finalize(

packages/interact-validate/src/schema/effects.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Keyframe, RangeOffset } from './primitives';
+import { Keyframe, RangeOffset, ReducedMotionHandling } from './primitives';
 import { withPluginFields } from './plugins';
 
 export const StateActionType = z.enum(['add', 'remove', 'toggle', 'clear']);
@@ -131,6 +131,7 @@ const EffectBase = {
   listContainer: z.string().optional(),
   listItemSelector: z.string().optional(),
   conditions: z.array(z.string().min(1)).optional(),
+  reducedMotionHandling: ReducedMotionHandling.optional(),
 };
 
 export const StateEffect = withPluginFields(

packages/interact-validate/src/schema/interactions.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { Condition } from './primitives';
+import { Condition, ReducedMotionHandling } from './primitives';
 import {
   Effect,
   ViewProgressEffect,
@@ -17,6 +17,7 @@ import { withPluginFields } from './plugins';
 import type { Path, SemanticIssue } from '../types';
 import { walkConfig } from '../walkConfig';
 import { collectSemanticWarnings } from '../semantic';
+import { checkReducedMotionErrors } from '../semantic/reducedMotion';
 
 export const TriggerType = z.enum([
   'hover',
@@ -58,6 +59,7 @@ const InteractionBase = {
   listContainer: z.string().optional(),
   listItemSelector: z.string().optional(),
   conditions: z.array(z.string().min(1)).optional(),
+  reducedMotionHandling: ReducedMotionHandling.optional(),
 };
 
 const hasEffectsOrSequences = (interaction: { effects?: unknown[]; sequences?: unknown[] }) =>
@@ -247,11 +249,14 @@ export const InteractConfigSchema = z
       onInteraction: (path, interaction) => {
         validateConditionReferences(ctx, path, configConditions, interaction.conditions);
       },
-      onEffect: (path, effect, isTopLevel) => {
+      onEffect: (path, effect, isTopLevel, owner, sequence) => {
         validateConditionReferences(ctx, path, configConditions, effect.conditions);
         if (!isTopLevel) {
           validateEffectReference(ctx, path, effect, configEffects);
         }
+        checkReducedMotionErrors(config, path, effect, isTopLevel, owner, sequence).forEach(
+          ({ severity: _, ...issue }) => ctx.addIssue(issue as any),
+        );
       },
       onSequence: (path, sequence, isTopLevel) => {
         validateConditionReferences(ctx, path, configConditions, sequence.conditions);
@@ -280,9 +285,11 @@ export const InteractConfigSchema = z
     walkConfig(config, {
       onInteraction: (_path, interaction) => {
         interaction.conditions?.forEach(Set.prototype.delete, conditionReferences);
+        effectIdReferences.delete(interaction.reducedMotionHandling!);
       },
       onEffect: (path, effect, isTopLevel) => {
         effect.conditions?.forEach(Set.prototype.delete, conditionReferences);
+        effectIdReferences.delete(effect.reducedMotionHandling!);
         collectEffectKeyframeNames(warnings, path, keyframeNames, (effect as any).keyframeEffect);
         if (!isTopLevel && effect.effectId) {
           if (!configEffects[effect.effectId]) {
@@ -298,6 +305,7 @@ export const InteractConfigSchema = z
       },
       onSequence: (_path, sequence, isTopLevel) => {
         sequence.conditions?.forEach(Set.prototype.delete, conditionReferences);
+        effectIdReferences.delete(sequence.reducedMotionHandling!);
         if (!isTopLevel && sequence.sequenceId) {
           sequenceIdReferences.delete(sequence.sequenceId);
         }

packages/interact-validate/src/schema/primitives.ts

@@ -1,5 +1,10 @@
 import { z } from 'zod';
 
+export const ReducedMotionMode = z.enum(['ignore', 'cancel', 'collapse']);
+
+// a string other than the modes is an effectId in config.effects
+export const ReducedMotionHandling = z.union([ReducedMotionMode, z.string().min(1)]);
+
 export const Keyframe = z.record(z.string(), z.union([z.string(), z.number()]));
 
 export const LengthPercentage = z

packages/interact-validate/src/schema/sequences.ts

@@ -1,5 +1,6 @@
 import { z } from 'zod';
 import { TimeEffect, TimeEffectRef, TimeTriggerType } from './effects';
+import { ReducedMotionHandling } from './primitives';
 
 const SequenceOptionsConfig = {
   delay: z.number().int().nonnegative().optional(),
@@ -10,6 +11,7 @@ const SequenceOptionsConfig = {
   triggerType: TimeTriggerType.optional(),
   sequenceId: z.string().optional(),
   conditions: z.array(z.string().min(1)).optional(),
+  reducedMotionHandling: ReducedMotionHandling.optional(),
 };
 
 export const SequenceConfig = z

packages/interact-validate/src/semantic/collectSemanticWarnings.ts

@@ -3,7 +3,8 @@
 // inspect the parsed config shape only. Warning/info checks are collected by
 // `collectSemanticWarnings` (consumed by the schema `transform`).
 
-import type { Path, SemanticIssue, AnyConfig, Visitors } from '../types';
+import type { SemanticIssue, AnyConfig } from '../types';
+import { walkConfig } from '../walkConfig';
 import { checkFunctionOffsetEasing } from './cssGeneration';
 import { checkCSSPropertyNames, checkInvalidInset } from './cssSyntax';
 import { checkSameElementRetrigger, checkHitAreaShift } from './fouc';
@@ -16,51 +17,23 @@ import { checkEmptyStyleProperties, checkStateRemoveWithoutEffectId } from './pa
 import { checkRecommendedFill } from './recommendedPatterns';
 import { findAnimationEndWarnings } from './animationEndGraph';
 import { checkNamedEffectParams } from './namedEffectParams';
-
-// Single traversal of top-level registry effects/sequences and per-interaction
-// effects/sequences, supplying each node's `path`, whether it is a top-level
-// registry definition, and its owning interaction (when known).
-export function walkConfig(config: AnyConfig, visitors: Visitors): void {
-  const { onInteraction, onEffect, onSequence } = visitors;
-
-  Object.entries(config.effects ?? {}).forEach(([id, effect]) => {
-    onEffect(['effects', id], effect, true, undefined);
-  });
-
-  Object.entries(config.sequences ?? {}).forEach(([id, sequence]) => {
-    onSequence(['sequences', id], sequence, true, undefined);
-    sequence.effects?.forEach((effect, ei) => {
-      onEffect(['sequences', id, 'effects', ei], effect, false, undefined);
-    });
-  });
-
-  config.interactions.forEach((interaction, i) => {
-    onInteraction?.(['interactions', i], interaction);
-    interaction.effects?.forEach((effect, ei) => {
-      onEffect(['interactions', i, 'effects', ei], effect, false, interaction);
-    });
-    interaction.sequences?.forEach((sequence, si) => {
-      const seqPath: Path = ['interactions', i, 'sequences', si];
-      onSequence(seqPath, sequence, false, interaction);
-      sequence.effects?.forEach((effect, ei) => {
-        onEffect([...seqPath, 'effects', ei], effect, false, interaction);
-      });
-    });
-  });
-}
+import { createReducedMotionWarnings } from './reducedMotion';
 
 // Collect every warning/info-level semantic issue (consumed by `transform`).
 export function collectSemanticWarnings(config: AnyConfig): SemanticIssue[] {
+  const reducedMotion = createReducedMotionWarnings(config);
   const warnings: SemanticIssue[] = [];
 
   walkConfig(config, {
     onInteraction: (path, interaction) => {
+      warnings.push(...reducedMotion.onInteraction(path, interaction));
       warnings.push(...checkListItemSelectorWithoutContainer(path, interaction));
       warnings.push(...checkRedundantSelector(path, interaction));
       warnings.push(...checkInvalidInset(path, interaction));
     },
     // checks that only look at depth>1 properties in effects/sequences do not need resolving
-    onEffect: (path, effect, isTopLevel, owner) => {
+    onEffect: (path, effect, isTopLevel, owner, sequence) => {
+      warnings.push(...reducedMotion.onEffect(path, effect, isTopLevel, owner, sequence));
       const { effectId } = effect;
       const resolvedEffect =
         !isTopLevel && effectId
@@ -78,6 +51,7 @@ export function collectSemanticWarnings(config: AnyConfig): SemanticIssue[] {
       warnings.push(...checkNamedEffectParams(path, effect));
     },
     onSequence: (path, sequence, isTopLevel, owner) => {
+      warnings.push(...reducedMotion.onSequence(path, sequence, isTopLevel, owner));
       const { sequenceId } = sequence;
       const resolvedSequence =
         !isTopLevel && sequenceId

packages/interact-validate/src/semantic/issue.ts

@@ -0,0 +1,8 @@
+import type { Path, SemanticIssue } from '../types';
+
+export const issue = (
+  path: Path,
+  domainCode: string,
+  message: string,
+  severity: SemanticIssue['severity'],
+) => ({ code: 'custom', path, message, params: { domainCode }, severity }) as SemanticIssue;

packages/interact-validate/src/semantic/namedEffectParams.ts

@@ -1,5 +1,6 @@
 import { Interact } from '@wix/interact';
 import type { AnyEffect, EffectParamSchema, EffectSchema, Path, SemanticIssue } from '../types';
+import { issue } from './issue';
 
 const LENGTH_REGEX = /^-?\d*\.?\d+(px|%|em|rem|vw|vh|vmin|vmax|ch|ex|cm|mm|in|pt|pc)?$/i;
 const ANGLE_REGEX = /^-?\d*\.?\d+(deg|rad|grad|turn)?$/i;
@@ -58,13 +59,6 @@ const PARAM_TYPES: Record<
   },
 };
 
-const issue = (
-  path: Path,
-  domainCode: string,
-  message: string,
-  severity: SemanticIssue['severity'],
-) => ({ code: 'custom', path, message, params: { domainCode }, severity }) as SemanticIssue;
-
 // the namedEffect's params against the schema of the effect registered on Interact under its type
 export function checkNamedEffectParams(path: Path, effect: AnyEffect): SemanticIssue[] {
   const { type, ...params } = effect.namedEffect ?? {};

packages/interact-validate/src/semantic/recommendedPatterns.ts

@@ -1,5 +1,5 @@
 import type { Path, SemanticIssue, AnyEffect, AnyInteraction } from '../types';
-import { RETRIGGER_TYPES } from '../types';
+import { RETRIGGER_TYPES, SCRUB_TRIGGERS } from '../types';
 
 function isKeyframeEffect(effect: AnyEffect): boolean {
   return !!(effect.namedEffect || effect.keyframeEffect);
@@ -12,7 +12,7 @@ export function checkRecommendedFill(
   owner?: AnyInteraction,
 ): SemanticIssue[] {
   if (effect.fill === 'both') return [];
-  const isScrubbed = owner?.trigger === 'viewProgress' || owner?.trigger === 'pointerMove';
+  const isScrubbed = !!owner?.trigger && SCRUB_TRIGGERS.includes(owner.trigger);
   const isToggling =
     effect.triggerType !== undefined && RETRIGGER_TYPES.includes(effect.triggerType);