Using the Paint API for dynamic borders

Creating visually expressive borders has always been a challenge in traditional CSS. Designers often rely on images, gradients, or complex layering tricks to achieve unique border styles, and developers commonly fall back on JavaScript-based solutions to animate or customize them. With CSS Houdini and the Paint API, however, dynamic borders become not only easier to implement but far more powerful and performant. This new generation of CSS features gives developers low-level access to the browser’s rendering pipeline, offering creative freedom that previously required heavy code or external assets. For beginners and intermediate developers who want to elevate their web design capabilities, the Paint API is one of the most exciting tools available today.
CSS Houdini introduces a set of APIs that expose previously invisible parts of the browser’s styling and layout engine. The Paint API—also known as the CSS Paint API or “paint worklet”—lets you programmatically draw graphics that can be applied wherever CSS accepts an image: backgrounds, masks, borders, and more. Instead of static images or CSS-only shapes, you can generate dynamic, resolution-independent visuals. When paired with custom properties, the Animation Worklet, and Typed OM, these visuals can react in real time to user input or application state, making web design far more interactive and expressive.
Why dynamic borders matter in modern web design
Borders play a much bigger role in UI aesthetics than many realize. Clean borders help define structure, emphasize key elements, convey hierarchy, and guide user attention. Dynamic borders—borders that respond to hover, click, scroll, or data changes—go a step further by enhancing interactivity and providing subtle visual feedback.
Traditionally, dynamic borders have been implemented through JavaScript DOM manipulation, pseudo-elements, or animated SVG strokes. While these methods work, they often require more code, add complexity, and create performance challenges on less powerful devices. The Paint API solves these problems by moving visual logic into the browser’s rendering engine where it belongs. This leads to better frontend performance, smoother animations, and more reliable browser rendering across different screen sizes.
How the Paint API improves border rendering compared to legacy techniques
Before CSS Houdini, developers frequently relied on:
• Gradient backgrounds applied to pseudo-elements
• SVG filters or strokes animated with JavaScript
• Border-image slices with PNG or SVG assets
• Canvas-based custom drawing injected into the DOM
Each of these approaches has limitations. They can pixelate when scaled, consume more memory, or require scripting on the main thread, which affects performance.
With the Paint API, borders are drawn inside a paint worklet running off the main thread. This means:
• Better performance since rendering is handled in the compositor
• No layout jank from script-driven animations
• Vector-like quality at any resolution
• Native support for custom properties that control styling
• Repaint only when needed, thanks to Typed OM precision
Setting up a paint worklet for dynamic borders
Implementing dynamic borders with the Paint API involves just a few steps, making it approachable even for developers new to Houdini.

1. Create a JavaScript file containing your paint worklet.
2. Register it in your CSS or JavaScript.
3. Apply the paint definition to a border using border-image-source or a similar property.
4. Expose variables using custom properties so your border can react dynamically.
   Here is a simplified example of a paint worklet file that draws a wavy border:

class WavyBorder {
  static get inputProperties() {
    return ['--wave-height', '--border-color'];
  }
  paint(ctx, size, props) {
    const waveHeight = parseInt(props.get('--wave-height')) || 8;
    const color = props.get('--border-color').toString() || 'black';
    ctx.strokeStyle = color;
    ctx.lineWidth = 2;
    ctx.beginPath();
    for (let x = 0; x < size.width; x++) {
      const y = Math.sin(x * 0.03) * waveHeight + waveHeight;
      ctx.lineTo(x, y);
    }
    ctx.stroke();
  }
}
registerPaint('wavy-border', WavyBorder);

Once registered, you can apply it in CSS:

.my-element {
  --wave-height: 10;
  --border-color: #4a90e2;
  border-image-source: paint(wavy-border);
  border-image-slice: 1;
  border-width: 4px;
  border-style: solid;
}

This example demonstrates how the Paint API lets you draw custom shapes that act as border images without external assets or heavy JavaScript logic.
Enhancing dynamic borders with custom properties and Typed OM
Custom properties (CSS variables) enable real-time control over worklet-generated borders. Instead of hard-coding colors or sizes inside the worklet, you can bind them to interactive states:
• Hover effects changing the border color
• Click events modifying border width
• Scroll percentage adjusting animation intensity
Using Typed OM ensures these values remain precise and typed during layout calculations, which improves performance and prevents string parsing overhead in the browser.
For instance, using JavaScript, you could update a custom property on scroll:

window.addEventListener('scroll', () => {
  const progress = window.scrollY / window.innerHeight;
  document.documentElement.style.setProperty('--wave-height', progress * 20);
});

This allows the border animation to grow or shrink smoothly based on scroll interaction, entirely handled within the browser’s optimized rendering pipeline.
Animating borders with the Animation Worklet
The Animation Worklet lets developers run animations off the main thread, similar to how the Paint API operates. When used together, they form a powerful duo: the Paint API draws the border, and the Animation Worklet updates its defining properties.
Instead of relying on requestAnimationFrame—which can lag or skip frames under heavy CPU load—the Animation Worklet ensures smooth frame pacing. This gives you better control over timing functions, easing curves, and synchronization with layouts generated by the Layout API.
You can animate custom properties that control borders, like --offset, --speed, or --pattern-density. The paint worklet will repaint only when those values change, meaning you get silky animations at high framerates.
Practical use cases for dynamic borders
Dynamic borders using the Paint API can improve real-world web design in meaningful ways.
• Highlighting input fields during user interaction
• Creating stylistic card components for marketing pages
• Building animated outlines for call-to-action buttons
• Designing artistic frames for portfolios
• Implementing data-driven border animations in dashboards
For example, on an ecommerce site, you might animate the border of a product card when it enters the viewport, drawing attention without relying on large images or JavaScript-heavy libraries. On a portfolio website, dynamic borders can add a handcrafted aesthetic that enhances the user experience.
Debugging and optimizing paint worklets for performance
To make dynamic borders efficient and production-ready, keep these tips in mind:
• Minimize loops and costly math inside the paint() function.
• Cache static values where possible.
• Avoid unnecessary repaints—tie custom properties only to the values that truly need to change.
• Use Typed OM to avoid string parsing overhead.
• Test across different browsers since Houdini support varies.
• Remember that simplicity often leads to better rendering performance.
By following these best practices, you maintain fast browser rendering and ensure your dynamic borders enhance your UI rather than slow it down.
Where dynamic creativity meets modern CSS
The Paint API transforms borders from rigid UI components into dynamic, creative elements that respond fluidly to user interactions. By combining CSS Houdini with the Paint API, custom properties, Typed OM, and the Animation Worklet, you gain granular control over browser rendering in ways that were previously impossible without JavaScript-heavy solutions. As web design trends continue to move toward immersive and interactive experiences, using dynamic borders powered by Houdini positions your projects at the cutting edge of frontend performance and creativity.