feat: add animated gradient border effect with customizable speed options

Author: snwolak

packages/react/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @protohiro/effects
 
+## 0.4.0
+
+### Minor Changes
+
+- Add animated gradient border flow with `animated` and `speed` options, CSS-only conic-gradient motion, reduced-motion fallback, and updated docs/tests.
+
 ## 0.3.4
 
 ### Patch Changes

packages/react/README.md

@@ -28,7 +28,7 @@ Peer dependencies:
 import { useGradientBorderEffect } from '@protohiro/effects';
 
 export function Button() {
-  const ref = useGradientBorderEffect({ thickness: 2, angle: 90 });
+  const ref = useGradientBorderEffect({ thickness: 2, angle: 90, animated: true });
   return <button ref={ref}>Click</button>;
 }
 ```
@@ -59,6 +59,18 @@ export function Button() {
 
 Gradient border ring on a single existing element with `border-radius` support and graceful fallback behavior.
 
+Options:
+
+- `thickness?: string | number`
+- `radius?: string | number`
+- `colors?: string`
+- `angle?: string | number`
+- `animated?: boolean`
+- `speed?: number`
+- `disabled?: boolean`
+
+When `animated` is enabled, the gradient colors flow around the border with CSS only. `speed` is a multiplier: `1` is the default, values above `1` are faster, and values below `1` are slower. The effect respects `prefers-reduced-motion` and falls back to a static ring when motion is reduced.
+
 ### `useSpotlightEffect(options)`
 
 Interactive spotlight and reveal overlay for cards, media surfaces, and CTA blocks.

packages/react/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@protohiro/effects",
-  "version": "0.3.4",
+  "version": "0.4.0",
   "description": "React hooks for hard CSS effects like gradient borders, spotlight reveal, and glass highlights without wrappers.",
   "license": "MIT",
   "type": "module",

packages/react/src/effects/useGradientBorderEffect.ts

@@ -10,14 +10,20 @@ const STYLE_ID = 'protohiro-effects-base';
 export function useGradientBorderEffect<T extends HTMLElement = HTMLElement>(
   options: GradientBorderOptions = {},
 ) {
+  const speed = typeof options.speed === 'number' && Number.isFinite(options.speed) ? options.speed : 1;
+  const resolvedSpeed = speed > 0 ? speed : 1;
+  const animationDuration = `${6 / resolvedSpeed}s`;
+
   const vars = useMemo(
     () => ({
       '--pe-gb-thickness': toCssLength(options.thickness),
       '--pe-gb-radius': toCssLength(options.radius),
       '--pe-gb-colors': options.colors,
       '--pe-gb-angle': toCssAngle(options.angle),
+      '--pe-gb-animation-duration': animationDuration,
+      '--pe-gb-animation-name': options.animated ? 'pe-gradient-border-flow' : 'none',
     }),
-    [options.thickness, options.radius, options.colors, options.angle],
+    [options.thickness, options.radius, options.colors, options.angle, animationDuration, options.animated],
   );
 
   return useCssEffect<T>({

packages/react/src/index.test.tsx

@@ -11,8 +11,13 @@ import {
   useSpotlightEffect,
 } from './index';
 
-function GradientProbe(props: { thickness?: number }) {
-  const ref = useGradientBorderEffect({ thickness: props.thickness ?? 3, colors: '#f00, #00f' });
+function GradientProbe(props: { thickness?: number; animated?: boolean; speed?: number }) {
+  const ref = useGradientBorderEffect({
+    thickness: props.thickness ?? 3,
+    colors: '#f00, #00f',
+    animated: props.animated,
+    speed: props.speed,
+  });
   return <button ref={ref}>Test</button>;
 }
 
@@ -68,17 +73,51 @@ function ComposedProbe() {
 
 describe('react effect hooks', () => {
   it('attaches and detaches class and vars', () => {
-    const { container, unmount } = render(<GradientProbe thickness={4} />);
+    const { container, unmount } = render(<GradientProbe thickness={4} animated speed={2} />);
     const button = container.querySelector('button');
 
     expect(button).not.toBeNull();
     expect(button?.classList.contains('pe-gradient-border')).toBe(true);
     expect(button?.style.getPropertyValue('--pe-gb-thickness')).toBe('4px');
+    expect(button?.style.getPropertyValue('--pe-gb-animation-duration')).toBe('3s');
+    expect(button?.style.getPropertyValue('--pe-gb-animation-name')).toBe('pe-gradient-border-flow');
 
     unmount();
 
     expect(button?.classList.contains('pe-gradient-border')).toBe(false);
     expect(button?.style.getPropertyValue('--pe-gb-thickness')).toBe('');
+    expect(button?.style.getPropertyValue('--pe-gb-animation-duration')).toBe('');
+    expect(button?.style.getPropertyValue('--pe-gb-animation-name')).toBe('');
+  });
+
+  it('toggles gradient border animation via options change', () => {
+    function Probe() {
+      const [animated, setAnimated] = useState(false);
+      const [speed, setSpeed] = useState(1);
+      const ref = useGradientBorderEffect({ thickness: 2, colors: '#f00, #00f', animated, speed });
+
+      return (
+        <>
+          <button ref={ref}>Test</button>
+          <button onClick={() => setAnimated((value) => !value)}>Toggle</button>
+          <button onClick={() => setSpeed(2)}>Faster</button>
+        </>
+      );
+    }
+
+    const { container, getByRole } = render(<Probe />);
+    const target = container.querySelector('button');
+
+    expect(target?.style.getPropertyValue('--pe-gb-animation-duration')).toBe('6s');
+    expect(target?.style.getPropertyValue('--pe-gb-animation-name')).toBe('none');
+
+    fireEvent.click(getByRole('button', { name: 'Toggle' }));
+
+    expect(target?.style.getPropertyValue('--pe-gb-animation-name')).toBe('pe-gradient-border-flow');
+
+    fireEvent.click(getByRole('button', { name: 'Faster' }));
+
+    expect(target?.style.getPropertyValue('--pe-gb-animation-duration')).toBe('3s');
   });
 
   it('updates css vars on options change', () => {

packages/react/src/shared/effectStyles.ts

@@ -14,8 +14,15 @@ export const EFFECT_STYLES = `
   border-radius: calc(var(--pe-gb-radius, 0px) + var(--pe-gb-thickness, 2px));
   box-sizing: border-box;
   padding: var(--pe-gb-thickness, 2px);
-  background: linear-gradient(var(--pe-gb-angle, 120deg), var(--pe-gb-colors, #5eead4, #0ea5e9));
+  background: conic-gradient(
+    from calc(var(--pe-gb-angle, 120deg) + var(--pe-gb-flow-progress, 0) * 1turn),
+    var(--pe-gb-colors, #5eead4, #0ea5e9)
+  );
   pointer-events: none;
+  animation-name: var(--pe-gb-animation-name, none);
+  animation-duration: var(--pe-gb-animation-duration, 6s);
+  animation-timing-function: linear;
+  animation-iteration-count: infinite;
 
   /* Hollow out the center so only the ring remains. */
   -webkit-mask:
@@ -28,14 +35,41 @@ export const EFFECT_STYLES = `
   mask-composite: exclude;
 }
 
+@property --pe-gb-flow-progress {
+  syntax: '<number>';
+  inherits: false;
+  initial-value: 0;
+}
+
+@keyframes pe-gradient-border-flow {
+  from {
+    --pe-gb-flow-progress: 0;
+  }
+
+  to {
+    --pe-gb-flow-progress: 1;
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .pe-gradient-border::before {
+    animation: none;
+    will-change: auto;
+  }
+}
+
 @supports not ((-webkit-mask-composite: xor) or (mask-composite: exclude)) {
   .pe-gradient-border::before {
     z-index: -1;
     inset: calc(var(--pe-gb-thickness, 2px) * -1);
     border-radius: calc(var(--pe-gb-radius, 0px) + var(--pe-gb-thickness, 2px));
     padding: 0;
     border: var(--pe-gb-thickness, 2px) solid;
-    border-image: linear-gradient(var(--pe-gb-angle, 120deg), var(--pe-gb-colors, #5eead4, #0ea5e9)) 1;
+    border-image: conic-gradient(
+        from calc(var(--pe-gb-angle, 120deg) + var(--pe-gb-flow-progress, 0) * 1turn),
+        var(--pe-gb-colors, #5eead4, #0ea5e9)
+      )
+      1;
   }
 }
 

packages/react/src/types.ts

@@ -8,6 +8,8 @@ export interface GradientBorderOptions extends EffectBaseOptions {
   radius?: string | number;
   colors?: string;
   angle?: string | number;
+  animated?: boolean;
+  speed?: number;
 }
 
 export interface GlowOptions extends EffectBaseOptions {