Fill a shape with a smooth color transition, using PDF vector shading.
dotnet add package RecursiveAI.OnePdfRequires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.
using OnePdf; using var doc = PdfDocument.CreateEmpty(); var page = doc.InsertBlankPage(0, 300, 200); using var content = page.BeginContent(); content.FillRectangle(30, 30, 240, 140, PdfGradient.Axial(30, 0, 270, 0, [ new(0, PdfGradientColor.Rgb(1, 0.8, 0)), new(1, PdfGradientColor.Rgb(0.8, 0, 0.2)) ])); content.Commit(); doc.Save("gradient.pdf");
Writes gradient.pdf: a yellow-to-red rectangle; prints nothing.
Unzip the example, then dotnet run.
The full program
The full program draws the same rectangle and reports the saved page size. Invalid stops, including decreasing positions or mixed color spaces, throw ArgumentException.
using OnePdf; using var doc = PdfDocument.CreateEmpty(); var page = doc.InsertBlankPage(0, 300, 200); using (var content = page.BeginContent()) { var gradient = PdfGradient.Axial(30, 0, 270, 0, [ new(0, PdfGradientColor.Rgb(1, 0.8, 0)), new(1, PdfGradientColor.Rgb(0.8, 0, 0.2)) ]); content.FillRectangle(30, 30, 240, 140, gradient); content.Commit(); } doc.Save("gradient.pdf"); Console.WriteLine("Saved gradient.pdf (300 x 200 pt)");
Saved gradient.pdf (300 x 200 pt)Variations
Radial shading inside an ellipse. Replace the FillRectangle call in the snippet at the top; the saved page has a white-to-blue elliptical fill at half opacity and prints nothing:
// Replace the FillRectangle call in the snippet at the top. content.Save(); content.Ellipse(30, 30, 240, 140); content.Clip(); content.SetFillOpacity(0.5); content.PaintGradient(PdfGradient.Radial( 150, 100, 0, 150, 100, 120, [ new(0, PdfGradientColor.Rgb(1, 1, 1)), new(1, PdfGradientColor.Rgb(0, 0.2, 0.8)) ])); content.Restore();
Related recipes
The short answer
Create a PdfGradient.Axial or PdfGradient.Radial and paint it with a page content builder. FillRectangle clips the gradient to a rectangle for you. For another shape, create a path, clip to it, and call PaintGradient. Commit the builder before saving the document.
The result is a PDF shading resource, not a bitmap of a gradient. The content creation documentation describes the low-level drawing API. The main example uses two RGB stops on a horizontal axis and writes a 300 by 200 point page. The variation shows a radial fill clipped to an ellipse.
What is a gradient fill?
A gradient fill changes color across an area according to a set of stops. Each stop has a position from 0 to 1 and a color. In an axial gradient, the positions run along a line between two points. In a radial gradient, they run between two circles described by their centers and radii.
The example’s axial line starts at x = 30 and ends at x = 270, matching the rectangle’s horizontal extent. Both y coordinates are zero, so the transition is horizontal regardless of the rectangle’s vertical position. The first stop is yellow and the last is dark red. Colors before the first stop and after the last stop are held; extendStart and extendEnd default to true and control whether end colors continue past the axis or circles.
Two stops become one exponential function; additional stops become a stitching function. Stops may share a position to create a hard edge, but their positions cannot decrease, and all their colors must use the same space: DeviceGray, DeviceRGB or DeviceCMYK. Validate those choices before drawing instead of expecting invalid input to be repaired.
How to make shape fill gradient?
For a rectangle, use the FillRectangle overload that takes a gradient. It combines a rectangle clip with painting. For an ellipse or arbitrary path, use the sequence in the variation: save the graphics state, define the shape, clip, paint, and restore. Restoring is important because otherwise the clip affects later content too.
PaintGradient fills the current clipping region. It does not infer a fill region from an unconsumed path, and the gradient’s axis does not itself limit painting to the rectangle you had in mind. Keeping the clip explicit makes the relation between geometry and paint clear.
Drawing coordinates use the page’s default user space: lower-left origin, y upward, with one unit equal to 1/72 inch times UserUnit. Page rotation and the CropBox are not applied to drawing coordinates. A transform, scale or rotation applied before painting carries the gradient with it. This differs from exported extraction geometry, which is already in upright page space.
How to fill in color in a PDF?
For a smooth fill, choose gradient colors and stops; for a uniform fill, use the builder’s ordinary color and path operations. Gradient colors at this pin have color components, not a per-stop alpha channel. The current fill opacity applies to the painted gradient as a whole. In the variation, SetFillOpacity(0.5) makes the entire radial shading translucent; it does not fade from opaque to transparent across its stops.
Every paint call adds a shading resource. A gradient object is immutable and can be reused across builders, but reusing the object does not mean a paint call adds no resource. Keep graphics-state changes scoped with save and restore, particularly if the same page later receives text or other artwork. Saving the PDF preserves vector shading; no raster conversion is required by this creation path.