SVG Filter primitiveUnits Attribute Guide

The primitiveUnits attribute on an SVG <filter> element defines the coordinate system and units used for geometric properties within its filter primitives. By setting this attribute, developers determine whether dimensions and positions—such as x, y, width, and height inside primitives like <feGaussianBlur> or <feOffset>—are calculated relative to the entire coordinate space or to the bounding box of the target element.

Supported Values for primitiveUnits

The primitiveUnits attribute accepts two standard values:

1. userSpaceOnUse (Default)

When primitiveUnits is set to userSpaceOnUse (or omitted, as it is the default), all coordinate and length values inside the filter primitives are resolved using the current user coordinate system established when the filter is referenced.

• Units: Standard SVG units (pixels, ems, percentages relative to the SVG viewport).
• Behavior: Absolute sizing. A blur radius or offset defined with a value of 10 represents 10 user-space units (typically 10 pixels), regardless of the size of the target element.

2. objectBoundingBox

When primitiveUnits is set to objectBoundingBox, all coordinates and dimensions within the filter primitives are resolved relative to the bounding box of the graphic element referencing the filter.

• Units: Normalized fractions ranging from 0 to 1 (or 0% to 100%).
• Behavior: Relative sizing. A coordinate value of 0.5 represents 50% of the target element’s width or height. This allows filter effects to scale proportionally with the element they are applied to.

Summary of Differences

• userSpaceOnUse: Best for fixed-pixel effects that should maintain a consistent absolute size regardless of how large or small the filtered element is rendered.
• objectBoundingBox: Best for responsive or scalable effects where the filter’s dimensions and positions need to adapt dynamically to the filtered element’s dimensions.