Apply a gradient fill

A gradient in IDML is a named swatch, applied to a shape exactly the way a flat colour is. Its direction belongs to the shape.

In short A Gradient is defined once in Resources/Graphic.xml, with two or more GradientStop children that each name an existing <Color> swatch. A shape uses it by pointing its FillColor at the gradient's Self id, the same attribute that takes a colour. The shape orients the blend: GradientFillAngle turns a linear gradient, counter-clockwise from left-to-right, so at 90 the first stop is at the bottom. A radial gradient is centred at the shape's GradientFillStart, with GradientFillLength as its radius. Download the sample.

The recipe

1. Make sure the stop colours exist. A gradient holds no colour of its own; each stop names an existing <Color> swatch. The example defines Color/Sun and Color/Sky as ordinary CMYK process colours.
2. Define the <Gradient> swatch in Resources/Graphic.xml, next to the colours. Give it a Self id (what shapes will reference), a Name, and Type="Linear" or Type="Radial".
3. Add the <GradientStop> children. Each names a colour in StopColor and places it with Location, a percentage from 0 to 100. The example puts Color/Sun at 0 and Color/Sky at 100. A stop's Midpoint governs the blend before that stop: it places the half-and-half point between the previous stop and this one, as a percentage of that segment (50 is halfway). In real documents a non-default midpoint therefore sits on a later stop, usually the last one at Location="100"; the first stop's midpoint has no segment to act on.
4. Apply it to a shape. Set the shape's FillColor to the gradient's Self id. In the example the rectangle carries FillColor="Gradient/SkySun".
5. Orient it on the shape, not on the gradient, so one swatch can fill several shapes in different directions:
   • for a linear gradient, GradientFillAngle in degrees. 0 runs the stops from left to right, and the angle turns counter-clockwise from there, so 90 runs them from bottom to top. The example uses 90, and InDesign draws Color/Sun, the first stop, at the bottom of the rectangle.
   • for a radial gradient, GradientFillStart (a point in the shape's own coordinates) is the centre, and GradientFillLength (in points) the radius at which the last stop is reached.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<idPkg:Graphic xmlns:idPkg="http://ns.adobe.com/AdobeInDesign/idml/1.0/packaging" DOMVersion="20.0">
  <Color Self="Color/Black" Model="Process" Space="CMYK" ColorValue="0 0 0 100" ColorOverride="Specialblack" Name="Black" ColorEditable="false" ColorRemovable="false" Visible="true"/>
  <Color Self="Color/Paper" Model="Process" Space="CMYK" ColorValue="0 0 0 0" ColorOverride="Specialpaper" Name="Paper" ColorEditable="true" ColorRemovable="false" Visible="true"/>
  <Color Self="Color/Sun" Model="Process" Space="CMYK" ColorValue="0 15 90 0" ColorOverride="Normal" Name="Sun" ColorEditable="true" ColorRemovable="true" Visible="true"/>
  <Color Self="Color/Sky" Model="Process" Space="CMYK" ColorValue="70 25 0 0" ColorOverride="Normal" Name="Sky" ColorEditable="true" ColorRemovable="true" Visible="true"/>
  <Gradient Self="Gradient/SkySun" Type="Linear" Name="Sky to Sun" ColorEditable="true" ColorRemovable="true" Visible="true">
    <GradientStop Self="Gradient/SkySun/stop0" StopColor="Color/Sun" Location="0" Midpoint="50"/>
    <GradientStop Self="Gradient/SkySun/stop1" StopColor="Color/Sky" Location="100" Midpoint="50"/>
  </Gradient>
</idPkg:Graphic>

Things to get right

• Define the gradient in the palette. A FillColor that names a gradient Graphic.xml does not define has nothing to paint with.
• Stops name colours, never values. You cannot write 0 15 90 0 on a stop; write a <Color> swatch and name its Self. Editing that swatch then updates every gradient that uses it.
• Put a midpoint on the stop it leads into. To skew the blend between two stops, set Midpoint on the second of them, not the first.
• Keep stops in ascending Location. Two stops are the minimum; each extra stop adds a band.
• Mind the direction of the angle. It is easy to read 90 as "downwards", as screen coordinates would suggest. In InDesign it means upwards: the first stop at the bottom.
• A tint is a different mechanism. For a lighter version of one colour rather than a blend between two, use a tint — see gradients & tints.

In Paged: linear and radial gradients, midpoints and GradientFillStart for radial gradients are read and drawn. Paged currently draws GradientFillAngle="90" from top to bottom, the opposite of InDesign; the example above shows the difference against InDesign's own rendering. It also applies a stop's Midpoint to the segment after the stop rather than before it. Supported · verified

For the palette as a whole — colours, process and spot, where swatches live — see Color & swatches.

Frequently asked questions

How does a shape reference a gradient? It points its FillColor at the gradient's Self id, exactly as it would at a colour. In the example the rectangle carries FillColor="Gradient/SkySun". There is no separate gradient-fill attribute.

Do gradient stops store their own colours? No. Each <GradientStop> names an existing <Color> swatch in StopColor. That indirection is why editing one swatch updates every gradient that uses it.

Which way does GradientFillAngle turn? Counter-clockwise from left-to-right. At 0 the first stop is on the left; at 90 the first stop is at the bottom and the last at the top. InDesign's rendering of the example shows the first stop, yellow, at the bottom of the rectangle.

Where is a radial gradient centred? At the shape's GradientFillStart, a point in the shape's own coordinates, with GradientFillLength as the radius. The angle does not change how a circle looks.

What's the difference between a gradient and a tint? A gradient blends between two or more colours across a shape; a tint is a lighter version of one colour. See gradients & tints.