react-gradient-borders

Animated gradient borders for React components using SVG-based path-following gradients.

Installation

npm install react-gradient-borders

Usage

import { GradientBorder } from 'react-gradient-borders';

function App() {
  return (
    <GradientBorder
      // Appearance
      colors={['#0066ff', '#ffdd00']} // default
      strokeWidth={3}                  // default
      borderRadius={12}                // default
      lineCapStart="square"            // 'round' | 'square' (default: 'square')
      lineCapEnd="square"              // 'round' | 'square' (default: 'square')
      // Animation
      animate={true}                   // default
      duration={2000}                  // default
      animationMode="once"             // 'once' | 'loop' (default: 'once')
      variant="default"                // 'default' | 'split' (default: 'default')
      reverse={false}                  // default
      startPosition="top-left"         // default
      // Trigger
      trigger="mount"                  // 'mount' | 'hover' | 'focus' | 'click' | 'manual'
      active={undefined}               // for trigger="manual" control
      showWhenInactive={false}         // default
      // Border Position
      borderPosition="inner"           // 'inner' | 'outer' (default: 'inner')
      borderOffset={0}                 // number | string (default: 0)
      // Ants Marching
      ants={false}                     // default
      antsDashWidth={20}               // default
      antsGapWidth={16}                // default
      antsSpeed={250}                  // default
      // Performance
      lazy={true}                      // default
      lazyRootMargin="100px"           // default
      resizeThrottle={150}             // default
      segments={200}                   // default
      // Styling
      style={{}}                       // default
      className=""                     // default
    >
      <div style={{ padding: 24, background: '#1a1a2e', borderRadius: 12 }}>
        <h2>Hello World</h2>
        <p>Content with an animated gradient border!</p>
      </div>
    </GradientBorder>
  );
}

Props

Prop	Type	Default	Description
children	ReactNode	-	Content to render inside the gradient border
colors	string[]	['#0066ff', '#ffdd00']	Array of colors for the gradient
startPosition	StartPosition	'top-left'	Where the gradient begins drawing from
strokeWidth	number	3	Width of the border stroke in pixels
lineCapStart	LineCap	'square'	Line cap for the start: 'round' or 'square'
lineCapEnd	LineCap	'square'	Line cap for the end/tip: 'round' or 'square'
borderRadius	number	12	Border radius in pixels
segments	number	200	Number of segments to divide the border into
duration	number	2000	Animation duration in milliseconds
animate	boolean	true	Whether to animate the border drawing in
trigger	Trigger	'mount'	What triggers the border to appear
animationMode	AnimationMode	'once'	Animation behavior: draw once or loop continuously
variant	Variant	'default'	Animation variant: draw from one point or split from both directions
reverse	boolean	false	Reverse the animation direction
active	boolean	-	For manual trigger control - whether the border is active
showWhenInactive	boolean	false	Show border when not triggered (for hover/focus/click modes)
lazy	boolean	true	Only render when visible in viewport
lazyRootMargin	string	'100px'	Margin around viewport for lazy loading
resizeThrottle	number	150	Throttle interval in ms for resize recalculations
ants	boolean	false	Enable ants marching (dashed line) effect
antsDashWidth	number	20	Width of each dash in pixels
antsGapWidth	number	16	Gap between dashes in pixels
antsSpeed	number	250	Speed of marching animation in ms per dash cycle
borderPosition	BorderPosition	'inner'	Border position: 'inner' or 'outer'
borderOffset	number | string	0	Offset the border (e.g., 4, "10px", "-5px")
style	CSSProperties	{}	Additional CSS styles for the container
className	string	''	Additional CSS class name for the container

Trigger

The trigger prop controls when the border appears:

• 'mount' (default) - Border appears on component mount
• 'hover' - Border appears on mouse hover
• 'focus' - Border appears when a child element is focused
• 'click' - Border toggles on click
• 'manual' - Control with the active prop

AnimationMode

The animationMode prop controls how the border animates:

• 'once' (default) - Draws the border once and stops
• 'loop' - Continuously animates the gradient around the border

Variant

The variant prop controls the drawing style:

• 'default' (default) - Draws from the start position in one direction
• 'split' - Draws from both directions simultaneously, meeting on the opposite side

BorderPosition

The borderPosition prop controls where the border is drawn:

• 'inner' (default) - Border is drawn inside the element bounds
• 'outer' - Border is drawn outside the element bounds

Use borderOffset to fine-tune the position. Positive values move outward, negative values move inward. Accepts numbers (pixels) or CSS length strings like "10px" or "-0.5rem".

StartPosition

The startPosition prop accepts either a preset string or a number from 0-1:

Preset positions:

• 'top-left' (default) - Starts at top-left corner
• 'top' - Starts at top center
• 'top-right' - Starts at top-right corner
• 'right' - Starts at right center
• 'bottom-right' - Starts at bottom-right corner
• 'bottom' - Starts at bottom center
• 'bottom-left' - Starts at bottom-left corner
• 'left' - Starts at left center

Custom position: Pass a number from 0 to 1 representing a position along the border path (0 = start of path, 1 = end of path).

Examples

Multi-color gradient

<GradientBorder colors={['#ff006e', '#8338ec', '#3a86ff', '#00f5d4']}>
  <div>Rainbow gradient border</div>
</GradientBorder>

Custom start position

<GradientBorder
  colors={['#ff006e', '#00f5d4']}
  startPosition="bottom"
>
  <div>Gradient starts from bottom center</div>
</GradientBorder>

Static gradient border (no animation)

<GradientBorder colors={['#ff006e', '#8338ec']} animate={false}>
  <div>Static gradient border</div>
</GradientBorder>

Custom colors and thickness

<GradientBorder
  colors={['#9b5de5', '#f15bb5']}
  strokeWidth={4}
  borderRadius={24}
>
  <div>Purple to pink gradient</div>
</GradientBorder>

Hover trigger

<GradientBorder
  colors={['#ff006e', '#8338ec', '#3a86ff']}
  trigger="hover"
  duration={800}
>
  <div>Border appears on hover</div>
</GradientBorder>

Focus trigger (great for inputs)

<GradientBorder
  colors={['#4facfe', '#00f2fe', '#43e97b']}
  trigger="focus"
  duration={600}
>
  <input type="text" placeholder="Focus me..." />
</GradientBorder>

Click toggle

<GradientBorder
  colors={['#ff006e', '#8338ec']}
  trigger="click"
>
  <div>Click to toggle border</div>
</GradientBorder>

Continuous loop animation

<GradientBorder
  colors={['#ff006e', '#8338ec', '#3a86ff', '#00f5d4']}
  animationMode="loop"
  duration={3000}
>
  <div>Gradient continuously animates around</div>
</GradientBorder>

Split animation (draw from both directions)

<GradientBorder
  colors={['#ff006e', '#8338ec', '#3a86ff', '#00f5d4']}
  variant="split"
  duration={2000}
>
  <div>Gradient draws from both directions and meets in the middle</div>
</GradientBorder>

Ants marching (dashed border)

<GradientBorder
  colors={['#ff006e', '#8338ec', '#3a86ff']}
  ants
  animationMode="loop"
>
  <div>Marching ants border effect</div>
</GradientBorder>

Outer border

<GradientBorder
  colors={['#ff006e', '#8338ec']}
  borderPosition="outer"
  strokeWidth={4}
>
  <div>Border drawn outside the element</div>
</GradientBorder>

Border with offset

<GradientBorder
  colors={['#ff006e', '#8338ec']}
  borderOffset={8}
>
  <div>Border offset 8px outward from inner edge</div>
</GradientBorder>

Manual control

function ControlledBorder() {
  const [active, setActive] = useState(false);

  return (
    <>
      <GradientBorder
        colors={['#ff006e', '#8338ec']}
        trigger="manual"
        active={active}
      >
        <div>Programmatically controlled</div>
      </GradientBorder>
      <button onClick={() => setActive(!active)}>Toggle</button>
    </>
  );
}

Replay animation

function ReplayableCard() {
  const [key, setKey] = useState(0);

  return (
    <>
      <GradientBorder
        key={key}
        colors={['#ff006e', '#8338ec', '#00f5d4']}
        duration={1500}
      >
        <div>Animated content</div>
      </GradientBorder>
      <button onClick={() => setKey(k => k + 1)}>
        Replay Animation
      </button>
    </>
  );
}

How It Works

The component creates an SVG overlay that draws line segments along a rounded rectangle path. Each segment is colored according to a linear interpolation across all colors in the gradient. When animate is true, segments are progressively revealed to create a drawing effect. The startPosition prop allows you to control where along the border path the gradient begins.

Browser Support

This component uses:

• ResizeObserver for responsive sizing
• IntersectionObserver for lazy loading
• requestAnimationFrame for smooth animations

These APIs are supported in all modern browsers.

License

MIT