SVG patternUnits vs patternContentUnits Sizing

This article explains how the patternUnits and patternContentUnits attributes control the coordinate systems and sizing behavior of SVG <pattern> elements. By defining how the pattern tile boundary and the internal graphic contents are measured, these two attributes determine whether an SVG pattern scales proportionally with the target shape or remains fixed to the overall canvas viewport.

The Role of patternUnits

The patternUnits attribute defines the coordinate system used for the pattern tile itself, specifically controlling the attributes x, y, width, and height on the <pattern> element.

• objectBoundingBox (Default): The pattern tile dimensions are calculated as fractions or percentages relative to the bounding box of the shape being filled or stroked. A width="0.2" and height="0.2" means the pattern repeats 5 times horizontally and 5 times vertically across the target element, scaling automatically if the target element changes size.
• userSpaceOnUse: The pattern tile dimensions are calculated using the current user coordinate system (typically pixels on the SVG canvas). A width="50" and height="50" creates a fixed 50×50 pixel tile regardless of the size or scale of the target element.

The Role of patternContentUnits

The patternContentUnits attribute defines the coordinate system used for the graphical elements nested inside the <pattern> tag, such as <rect>, <circle>, or <path>.

• userSpaceOnUse (Default): The shapes inside the pattern use absolute SVG coordinate values (pixels). A <circle r="10" /> retains a 10-pixel radius irrespective of the bounding box of the target shape.
• objectBoundingBox: The internal shapes are defined using fractional values (ranging from 0.0 to 1.0) relative to the size of the target element filling the pattern. For instance, a <rect width="0.5" height="0.5" /> will cover half the width and height of the filled element.

How the Two Attributes Interact

The combination of both attributes dictates whether a pattern behaves as a fixed-size repeating texture or a dynamically scaling vector graphic:

1. Fixed Texture (patternUnits="userSpaceOnUse" and patternContentUnits="userSpaceOnUse"): The tile and the graphics inside it maintain fixed pixel values. As the target shape grows, more tiles appear without stretching the internal graphics.

2. Fully Scalable Pattern (patternUnits="objectBoundingBox" and patternContentUnits="objectBoundingBox"): Both the tile size and the internal graphics are proportional to the filled element. Scaling the target element scales the entire pattern proportionally, but internal coordinates must be authored as decimal fractions (e.g., cx="0.5").

3. Hybrid Setup (patternUnits="userSpaceOnUse" with viewBox): A common alternative to manipulating patternContentUnits is defining patternUnits="userSpaceOnUse" alongside a viewBox and preserveAspectRatio on the <pattern>. This allows authoring internal contents in standard pixel units while letting the tile boundary scale and map properly to target surfaces.