Gradient
gradient
The gradient parameter draws a color gradient over the picture. Its most common use is a scrim: a dark gradient along one edge that makes overlaid text readable without darkening the whole image.
It takes 2 to 16 comma-separated colors, as hexadecimal values or CSS color keywords.
In the 8-digit form the alpha comes first: AARRGGBB. This is the single most common mistake with this parameter, because CSS puts alpha last. cc000000 is 80% black, which is what you want for a scrim; 000000cc is a transparent black that will appear to do nothing.
A list with fewer than 2 colors, more than 16, or any unparseable color is ignored in its entirety, and no companion parameter is read either.
Transparency Is Preserved
The overlay keeps the picture’s own transparency: a transparent pixel stays transparent rather than taking on the gradient color. This differs from CSS on purpose, and it is what lets a gradient be drawn over a cut-out without filling in its background.
Companion Parameters
| Parameter | What it controls |
|---|---|
gradient-type | Linear or radial |
gradient-angle | The direction of a linear gradient |
gradient-stops | Where each color sits |
gradient-cs and gradient-hue | How colors are interpolated |
gradient-mode | The blend mode used against the picture |
gradient-alpha | The overlay’s overall opacity |
gradient-mask | Fades the picture out instead of painting over it |
The radial shape is set by gradient-radial-shape, gradient-radial-size, gradient-radial-x and gradient-radial-y.
On Video
The Video API draws gradient on video output, and on stills and GIFs made from a video. Only gradient-mode=normal is drawn there, color adjustments such as sat or blur land on top of the gradient rather than under it, and mark-gradient is drawn on video output but not on stills. Spritesheets ignore it.