a:gradFill (Gradient Fill)

Specifies a gradient fill with color stops that smoothly transitions between colors across a shape, line, or text.

Parent elements

Child elements

Description

\:gradFill\ is the DrawingML gradient fill element that applies a color gradient to shapes, lines, text bodies, and grouped shapes. It is defined in ECMA-376 Part 1 §20.1.4.8.

Gradient fills enable smooth color transitions from one color to another, creating sophisticated visual effects. The gradient can flow in two modes:

Linear Gradient (\:lin): Colors transition along a straight path with optional rotation and scaling
Path Gradient (\:path): Colors radiate from a rectangular or elliptical path (like a sun radiating outward)

Key features:

Multiple color stops define the gradient spectrum, each with a position (0–100000 representing 0–100%)
Linear gradients use angle-based direction (0–21600000 in 60,000ths of a degree)
Path gradients define a focus rectangle for radial effects
Optional flipping (x, y, or both axes) and rotation with shape
Gradient fills enhance modern, professional-looking designs
Used extensively in charts, data visualizations, and presentation graphics

Gradient fills are more computationally intensive than solid fills but provide better visual hierarchy and polish.

Attributes

Attribute	Type	Range/Values	Default	Description
\lip\	\ST_ShapeFlipValues\	none, x, y, xy	none	Flip the gradient direction along specified axes.
\
otWithShape\	\xsd:boolean\	0, 1 (true, false)	1	If true, gradient rotates when the shape is rotated.
\
oFill\	\xsd:boolean\	0, 1	0	If true, no fill is applied (overrides gradient).
\useShapeAnchor\	\xsd:boolean\	0, 1	0	If true, use shape anchor point; if false, use shape bounds.

Content Model

\:gradFill\ contains:

Exactly one \:gsLst\ (gradient stops list) – defines colors and positions
Exactly one of: \:lin\ (linear gradient) OR \:path\ (path/radial gradient)

Child Elements Table

Element	Occurrence	Purpose
\:gsLst\	1	Gradient stops list with color definitions.
\:lin\	0–1	Linear gradient properties for directional color flow.
\:path\	0–1	Path gradient properties for radial fill effects.

Examples

Linear Gradient (Blue to White)

<a:spPr>
  <a:gradFill rotWithShape=\"1\">
    <a:gsLst>
      <a:gs pos=\"0\">
        <a:srgbClr val=\"0070C0\"/>
      </a:gs>
      <a:gs pos=\"100000\">
        <a:srgbClr val=\"FFFFFF\"/>
      </a:gs>
    </a:gsLst>
    <a:lin ang=\"0\" scaled=\"1\"/>
  </a:gradFill>
</a:spPr>

using DocumentFormat.OpenXml.Drawing;

var spPr = new ShapeProperties();
var gradFill = new GradientFill { RotateWithShape = true };
var gsLst = new GradientStopList();

var gs1 = new GradientStop { Position = 0 };
gs1.Append(new RgbColorModelHex { Val = \"0070C0\" });
gsLst.Append(gs1);

var gs2 = new GradientStop { Position = 100000 };
gs2.Append(new RgbColorModelHex { Val = \"FFFFFF\" });
gsLst.Append(gs2);

gradFill.Append(gsLst);
var lin = new LinearGradientFillProperties { Angle = 0, Scaled = true };
gradFill.Append(lin);
spPr.Append(gradFill);

Multi-Color Gradient (Red → Yellow → Green)

<a:gradFill>
  <a:gsLst>
    <a:gs pos=\"0\">
      <a:srgbClr val=\"FF0000\"/>
    </a:gs>
    <a:gs pos=\"50000\">
      <a:srgbClr val=\"FFFF00\"/>
    </a:gs>
    <a:gs pos=\"100000\">
      <a:srgbClr val=\"00B050\"/>
    </a:gs>
  </a:gsLst>
  <a:lin ang=\"2700000\" scaled=\"1\"/>
</a:gradFill>

var gradFill = new GradientFill();
var gsLst = new GradientStopList();

var gs1 = new GradientStop { Position = 0 };
gs1.Append(new RgbColorModelHex { Val = \"FF0000\" });
gsLst.Append(gs1);

var gs2 = new GradientStop { Position = 50000 };
gs2.Append(new RgbColorModelHex { Val = \"FFFF00\" });
gsLst.Append(gs2);

var gs3 = new GradientStop { Position = 100000 };
gs3.Append(new RgbColorModelHex { Val = \"00B050\" });
gsLst.Append(gs3);

gradFill.Append(gsLst);
var lin = new LinearGradientFillProperties { Angle = 2700000, Scaled = true };
gradFill.Append(lin);

Radial Gradient (Center-radiating)

<a:gradFill>
  <a:gsLst>
    <a:gs pos=\"0\">
      <a:srgbClr val=\"FFFFFF\"/>
    </a:gs>
    <a:gs pos=\"100000\">
      <a:srgbClr val=\"000000\"/>
    </a:gs>
  </a:gsLst>
  <a:path path=\"circle\">
    <a:fillToRect l=\"50000\" t=\"50000\" r=\"50000\" b=\"50000\"/>
  </a:path>
</a:gradFill>

var gradFill = new GradientFill();
var gsLst = new GradientStopList();

var gs1 = new GradientStop { Position = 0 };
gs1.Append(new RgbColorModelHex { Val = \"FFFFFF\" });
gsLst.Append(gs1);

var gs2 = new GradientStop { Position = 100000 };
gs2.Append(new RgbColorModelHex { Val = \"000000\" });
gsLst.Append(gs2);

gradFill.Append(gsLst);
var path = new PathGradientFillProperties { Path = PathFillModeValues.Circle };
path.Append(new FillToRectangle { Left = 50000, Top = 50000, Right = 50000, Bottom = 50000 });
gradFill.Append(path);

Gradient with Transparency

<a:gradFill flip=\"none\" rotWithShape=\"0\">
  <a:gsLst>
    <a:gs pos=\"0\">
      <a:srgbClr val=\"4472C4\">
        <a:alpha val=\"100000\"/>
      </a:srgbClr>
    </a:gs>
    <a:gs pos=\"100000\">
      <a:srgbClr val=\"4472C4\">
        <a:alpha val=\"20000\"/>
      </a:srgbClr>
    </a:gs>
  </a:gsLst>
  <a:lin ang=\"5400000\" scaled=\"1\"/>
</a:gradFill>

var gradFill = new GradientFill { Flip = FlipValues.None, RotateWithShape = false };
var gsLst = new GradientStopList();

var gs1 = new GradientStop { Position = 0 };
var color1 = new RgbColorModelHex { Val = \"4472C4\" };
color1.Append(new Alpha { Val = 100000 });
gs1.Append(color1);
gsLst.Append(gs1);

var gs2 = new GradientStop { Position = 100000 };
var color2 = new RgbColorModelHex { Val = \"4472C4\" };
color2.Append(new Alpha { Val = 20000 });
gs2.Append(color2);
gsLst.Append(gs2);

gradFill.Append(gsLst);
var lin = new LinearGradientFillProperties { Angle = 5400000, Scaled = true };
gradFill.Append(lin);

Gradient with Scheme Colors (Theme-aware)

<a:gradFill rotWithShape=\"1\">
  <a:gsLst>
    <a:gs pos=\"0\">
      <a:schemeClr val=\"accent1\">
        <a:tint val=\"50000\"/>
      </a:schemeClr>
    </a:gs>
    <a:gs pos=\"100000\">
      <a:schemeClr val=\"accent1\">
        <a:shade val=\"50000\"/>
      </a:schemeClr>
    </a:gs>
  </a:gsLst>
  <a:lin ang=\"2700000\" scaled=\"1\"/>
</a:gradFill>

var gradFill = new GradientFill { RotateWithShape = true };
var gsLst = new GradientStopList();

var gs1 = new GradientStop { Position = 0 };
var color1 = new SchemeColor { Val = ColorSchemeIndexValues.Accent1 };
color1.Append(new Tint { Val = 50000 });
gs1.Append(color1);
gsLst.Append(gs1);

var gs2 = new GradientStop { Position = 100000 };
var color2 = new SchemeColor { Val = ColorSchemeIndexValues.Accent1 };
color2.Append(new Shade { Val = 50000 });
gs2.Append(color2);
gsLst.Append(gs2);

gradFill.Append(gsLst);
var lin = new LinearGradientFillProperties { Angle = 2700000, Scaled = true };
gradFill.Append(lin);

Reference Tables

Linear Gradient Angles

Angle	Degrees	Direction	Use Case
0	0°	Right (→)	Left-to-right fade
2700000	90°	Down (↓)	Top-to-bottom fade
5400000	180°	Left (←)	Right-to-left fade
8100000	270°	Up (↑)	Bottom-to-top fade

Gradient Stop Positions

Position	Percentage	Meaning
0	0%	Start color
25000	25%	Quarter point
50000	50%	Midpoint
75000	75%	Three-quarter point
100000	100%	End color

Notes

Element Relationships

Parents: Shape properties (\:spPr), group properties (\:grpSpPr), line properties (\:ln), text body (\:txBody)
Fill Priority: Only one fill type allowed per container; first defined fill is applied
Children: Must contain gradient stops (\:gsLst) and exactly one gradient direction (\:lin\ or \:path)

Implementation Details

Gradient Stops: Position values must be in ascending order (0–100000); minimum 2 stops required
Color Modifiers: Stop colors support tint, shade, alpha, lumMod, lumOff for blending effects
Linear vs Radial: Linear gradients render faster; path gradients enable spotlight/halo effects
Rotation:
otWithShape="1"\ maintains gradient angle relative to shape orientation
Theme Integration: Scheme colors enable automatic theme switching; RGB colors are static
Performance: Gradients consume more resources than solid fills; use judiciously in large documents
Compatibility: Cross-Office rendering supported; some exotic gradient combinations may degrade in older clients