How Does the SMIL restart Attribute Work?

The restart attribute in Synchronized Multimedia Integration Language (SMIL) and SVG animation defines whether and when an active or completed animation element can be triggered again before or after it finishes its cycle. By default, animations may react to events repeatedly, but using the restart attribute gives developers explicit control over element reactivation, preventing unwanted animation restarts, race conditions, or chaotic visual glitches during user interactions.

Core Values of the restart Attribute

The restart attribute accepts one of three distinct values to dictate runtime behavior:

• always (Default): The animation can be restarted at any point in time. If an event or timing condition triggers while the animation is currently running, the element immediately resets to its starting point and plays again from the beginning.
• whenNotActive: The animation can only be triggered if it is not currently playing. Any trigger events received while the animation is active are ignored. Once the active duration ends, the animation becomes eligible to start again upon the next trigger.
• never: The animation can only run once during the lifetime of the document or timeline context. Once started, all subsequent trigger conditions and events are permanently ignored, ensuring single-execution behavior.

Practical Use Cases in SVG and SMIL

Controlling reactivation behavior is essential for creating predictable interactive animations:

• Preventing Rapid-Click Bugs: Interactive buttons or icons set to animate on click or mouseenter can stutter if clicked repeatedly. Setting restart="whenNotActive" ensures the full animation sequence finishes smoothly before accepting a new trigger.
• One-Time Intro Sequences: Onboarding highlights, entrance transitions, or single-use state morphs benefit from restart="never", guaranteeing that user interaction will not replay an introductory animation.
• Immediate Feedback Loops: Controls like pulsating alerts or reset buttons often require immediate cancellation and replay on every user click, making restart="always" the appropriate choice.

Managing the restart attribute ensures that declarative animations behave consistently across different user interaction patterns without requiring custom JavaScript state tracking.