gradientUnits

gradientUnits is an attribute on SVG gradient elements (such as linearGradient and radialGradient) that specifies the coordinate system used to interpret the gradient’s geometry. It accepts two values: objectBoundingBox and userSpaceOnUse. The default is objectBoundingBox when the attribute is not present.

In objectBoundingBox mode, gradient coordinates are defined as fractions of the target element’s bounding box. For a linear gradient, x1, y1, x2, and y2 describe a vector within that box, typically expressed as percentages or values in the 0 to 1 range. For a radial gradient, cx, cy, and r denote the center and radius relative to the element’s bounding box. This mode ensures the gradient scales with the element’s size and aspect ratio.

In userSpaceOnUse mode, gradient coordinates are defined in the current user coordinate system, i.e., in absolute or transformed units of the SVG canvas. This means x1, y1, x2, y2 (and cx, cy, r for radial gradients) are interpreted with respect to the overall document coordinates rather than the element’s bounding box. Changes to the element’s size do not automatically scale the gradient, though gradientTransform can still be applied to modify it.

gradientUnits interacts with gradientTransform, which can be used to rotate, scale, or translate the gradient after its base coordinates are established. Understanding gradientUnits is essential for predictable gradient alignment across varying element sizes and layouts.