Understanding SVG viewBox Letterboxing and Slicing

This article explains how Scalable Vector Graphics (SVG) handle mismatched aspect ratios between the rendering viewport and the internal viewBox. When these dimensions do not match, the preserveAspectRatio attribute dictates whether the graphic scales uniformly to fit entirely inside the container (letterboxing) or scales to cover the entire container (slicing). Understanding this calculation ensures precise visual rendering and responsive behavior across different screen sizes.

The Viewport vs. The viewBox

An SVG utilizes two coordinate systems: 1. The Viewport: The outer box defined by the SVG’s width and height attributes (or computed CSS dimensions). 2. The viewBox: The internal coordinate space defined by viewBox="min-x min-y width height".

When the aspect ratio of the viewport does not equal the aspect ratio of the viewBox, SVG cannot scale the width and height equally without either distorting the graphic, clipping parts of it, or leaving empty space.

The preserveAspectRatio Attribute

Uniform scaling is controlled by the preserveAspectRatio attribute, which takes two values: an alignment specifier and an optional meetOrSlice parameter.

preserveAspectRatio="<align> [<meetOrSlice>]"

The meetOrSlice parameter defaults to meet if omitted.

How Letterboxing Works (meet)

The meet option scales the entire viewBox up or down until it reaches the boundaries of the viewport while preserving its original aspect ratio.

• Scale Calculation: The rendering engine computes horizontal and vertical scale factors: \[\text{Scale}_X = \frac{\text{Viewport Width}}{\text{viewBox Width}}\] \[\text{Scale}_Y = \frac{\text{Viewport Height}}{\text{viewBox Height}}\] The smaller of the two scale factors is applied: \[\text{Scale} = \min(\text{Scale}_X, \text{Scale}_Y)\]
• Visual Outcome: The entire graphic remains fully visible within the viewport.
• Letterboxing/Pillarboxing: Because the graphic is scaled by the minimum factor, one dimension will have excess space. If the viewport is wider than the viewBox, horizontal space (pillarboxing) appears. If the viewport is taller, vertical space (letterboxing) appears.
• Alignment: The <align> parameter (e.g., xMidYMid, xMinYMin) determines how the scaled viewBox is positioned within the leftover space.

How Slicing Works (slice)

The slice option scales the viewBox uniformly until it completely covers the entire viewport area.

• Scale Calculation: The rendering engine computes the same scale factors but chooses the larger value: \[\text{Scale} = \max(\text{Scale}_X, \text{Scale}_Y)\]
• Visual Outcome: The SVG fills the entire container without leaving any empty margins or gaps.
• Slicing (Cropping): Because the graphic is scaled by the maximum factor, the dimension that exceeds the viewport boundaries is clipped outside the rendering area.
• Alignment: The <align> parameter determines which portion of the graphic remains visible and which edges get cropped. For example, xMidYMid slice crops equally from both sides or the top and bottom, keeping the center of the graphic in view.

Practical Comparison

• Use meet when the entire graphic must remain visible (e.g., icons, logos, technical diagrams).
• Use slice when the SVG serves as a background, pattern, or decorative element where full coverage of the container is preferred over complete visibility of the artwork.
• Use none (preserveAspectRatio="none") if uniform scaling is not required and the graphic should stretch to fill the viewport, completely disabling both letterboxing and slicing.