Recursive AI

Render CSS masks and clip paths in C#

OneRender is a free, open-source HTML and CSS rendering library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

Clip paths cut shapes; masks fade them. Save both effects in a PNG.

Terminal
dotnet add package RecursiveAI.OneRender.Image

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
using OneRender.Image;
var image = HtmlRender.ToImage("""
<div style="width:80px;height:80px;
background:blue;clip-path:circle(50%);
mask-image:
linear-gradient(black,transparent)"></div>
""");
File.WriteAllBytes("masked.png", image.ToPng());
Console.WriteLine("Saved masked.png");
Text
Saved masked.png

Unzip the example, then dotnet run.

The full program

All HTML and CSS are embedded in Program.cs; no input files are needed.

C#
using OneRender.Image;
 
string html = """
<style>
body { margin: 0 }
div { width: 100px; height: 100px; background: #0066cc;
      clip-path: circle(50%);
      mask-image: linear-gradient(to right, transparent, black) }
</style><div></div>
""";
var image = HtmlRender.ToImage(html,
    new HtmlRenderOptions { Width = 100, Height = 100 });
File.WriteAllBytes("masked.png", image.ToPng());
Console.WriteLine($"masked.png: {image.Width}x{image.Height}");
Text
masked.png: 100x100

The full program writes a 100-by-100 image: the circle clips the blue square, and the horizontal gradient fades it from left to right over the default white page. A rasterization resource limit throws RasterizationException rather than returning a completed image.

Blue circle fading from white on the left to blue on the right

Variations

Replace the full program’s clip-path declaration with a triangle; leave the gradient mask in place:

CSS
clip-path: polygon(50% 0, 100% 100%, 0 100%);
Text
masked.png: 100x100

Blue triangle fading from white on the left to blue on the right

The short answer

Pass HTML containing clip-path and mask-image to HtmlRender.ToImage, then write ToPng() to disk.

How do I render a CSS clip-path example in C#?

Give the element a width, height and visible background, then set its clipping shape. The circle in the full program reveals the center of the square and removes its corners. The polygon variation connects three percentage coordinates to reveal a triangle instead. Change only the clipping declaration to compare the shapes without also changing layout or color.

Clipping affects painting, not the element’s layout box. As web.dev’s clipping guide explains, surrounding text does not reflow to follow the clipping outline. When a clipped element still occupies a rectangular space in your layout, that is different from a failed clip.

Set the viewport independently of the element dimensions. Here both are 100 pixels square, and the body margin is zero so the shape begins at the viewport origin. A default body margin would shift the shape; a smaller viewport would cut off part of it. Those layout choices can resemble an incorrect clip if you inspect only the saved file.

How does CSS mask-image differ from clip-path?

A clip defines a geometric visible region. A mask supplies coverage that can be partially transparent; see the masking guide. In this example, the gradient runs from transparent to opaque black. Its alpha, not its black color, controls how much of the blue element remains visible. With the default white page behind it, the faded end appears white rather than becoming a transparent PNG corner.

OneRender’s display-list documentation describes alpha and luminance mask modes and the add, subtract, intersect and exclude layer operators. An alpha mask uses opacity; a luminance mask uses brightness multiplied by opacity. Choose the mode deliberately when replacing a gradient with an image: opaque black is coverage in alpha mode but darkness in luminance mode.

The documented display-list cap is 16 mask layers per mask. Masks with no layers hide their content. Deeply nested effects also consume rasterizer layer memory, so this is not an unlimited compositor. For predictable output, start with one clipping shape and one gradient as above, then add the effects your document actually needs. The worked examples establish circle, polygon and gradient behavior; they do not imply that every possible CSS masking syntax is interchangeable.

All onerender recipes