SVG viewBox – How does the SVG viewBox work?

SVG viewBox

The viewBox attribute is a powerful feature in SVG that controls the scaling and positioning of graphics within the viewport. It acts as a flexible window within the SVG canvas, allowing you to control how much of the drawing is visible and how it should fit within a given space. One of the key benefits of viewBox is its ability to enable scaling. This means that SVG graphics can be resized without losing quality or distorting their proportions.

This article will look at how viewBox works, its syntax, and practical examples of SVG scaling and positioning. You’ll learn:

• The difference between SVG canvas, viewport, and viewBox
• How to scale SVG using viewBox
• How to crop SVG or position SVG using viewBox

SVG canvas, viewport, and coordinate systems

To start the conversation, it would be helpful (even necessary!) to define the terms and definitions that we will use when describing how an SVG viewBox works.

1. SVG canvas. The canvas is the infinite virtual space where all SVG graphics are drawn. Think of it as an endless sheet of paper without any borders. You don’t see the entire canvas—only the part defined by the viewport.

2. SVG viewport is the visible area where the SVG content is displayed. It’s defined by the width and height attributes of the <svg> element. The viewport acts like a window through which you view a specific portion of the SVG canvas. Here, the viewport is 500×500 pixels, even though the canvas is infinite:

<svg width="500" height="500">...</svg>

3. Initial coordinate system (Initial CS) is the default system applied to the SVG canvas. It works like a two-dimensional x-y plane with the point of origin (0,0) in the top left corner. The positive x-direction is to the right, and the positive y-direction is to the bottom. The default SVG units are pixels. For more information about SVG Coordinate Systems and Units, please follow this link.

4. User coordinate system (User CS) is the system that defines how user units (the coordinates you specify) are mapped to screen units (actual pixels). It determines the positioning and sizing of SVG elements and is flexible – it can be scaled, rotated, skewed, or flipped through transformations. Applying a viewBox attribute to the <svg> element can transform the user CS relative to the initial CS, controlling how SVG content fits within the viewport.

How viewBox works

The viewBox attribute sets a user coordinate system, which may not be the same as the initial one. It defines a rectangular region of the SVG canvas and consists of four values:

• min-x – the x-coordinate of the top-left corner of the viewBox
• min-y – the y-coordinate of the top-left corner of the viewBox
• width – the width of the viewBox rectangle
• height – the height of the viewBox rectangle

Values of the viewBox attribute must be placed inside quotes: viewBox= "min-x min-y width height". When specified, the viewBox attribute maps the defined canvas area to the SVG’s viewport, allowing for scaling and cropping.

By manipulating the first two parameters (min-x and min-y), we can shift the origin of the user coordinate system relative to the initial one and thus control the cropping of the SVG. Changing the next two parameters (width and height) results in the scaling of the SVG. Changing all four parameters will result in a complex image change, including cropping and scaling.

The figure below shows three cases of using a viewBox – in the first case, the position and size of the viewport and viewBox are the same, so there is no scaling. In the second case, the viewBox is larger than the viewport, which results in a smaller image; in the third case, the viewBox is smaller, which results in a larger image.

Note: In all figures in this article, the viewport area and sizes are shown in green, and the viewBox data are shown in blue.

The following figure illustrates how changing the width and height parameters in the viewBox attribute affects the scaling of the SVG image:

XML code for the flower image that we use as an example in this article:

<svg width="250" height="250" viewBox="0 0 250 250" xmlns="http://www.w3.org/2000/svg">
<rect x="0" y="0" height="100%" width="100%" fill="none" stroke="grey" stroke-width="1" />
    <g fill="RoyalBlue">
        <rect x="25" y="100" rx="25" ry="25" width="200" height="56" />
        <rect x="25" y="100" rx="25" ry="25" width="200" height="56" transform="rotate(90 125 128)" />
        <rect x="25" y="100" rx="25" ry="25" width="200" height="56" transform="rotate(-45 125 128)" />
        <rect x="25" y="100" rx="25" ry="25" width="200" height="56" transform="rotate(45 125 128)" />
    </g>
    <circle cx="125" cy="128" r="28" stroke="pink" stroke-width="50" stroke-dasharray="3 13" fill="Orange" />
    <circle cx="125" cy="128" r="5" />
</svg>

How scaling works with viewBox

Let’s start by looking at scaling, which we can do with the last two viewBox parameters: width and height. We will leave the first two parameters at 0 0 for now. If the SVG viewBox width and height parameters are the same dimensions as the viewport, then there is no zoom in or zoom out. This means that nothing changes. But if we make these two numbers larger than the viewport dimensions, we actually zoom out. And if we make them smaller, we’ll zoom in.

SVG zooming out with viewBox

Why does the image scale if the viewport and viewBox sizes (width and height) do not match? The main feature of the viewBox is that it is a specific canvas area that the user selects by specifying its coordinates and size as values ​​in the viewBox attribute. This area is then fully fitted into the viewport, and scaling inevitably occurs.

So

• In the first picture, we see an image of a flower associated with the initial coordinate system in the viewport.
• In the second picture, we see a viewBox that the user has selected and thus introduced a new coordinate system – the user one.
• In the third picture, we see how the viewBox fits completely into the viewport and how the two coordinate systems – the initial and the user ones – are related. The user coordinate system unit became equal to 0.5 units of the source coordinate system.

By default, the viewBox scales the content proportionally. The preserveAspectRatio attribute can be used to control how the scaling is applied.

SVG zooming in with viewBox

When the viewBox is smaller than the viewport’s width and height, the SVG content is scaled up (enlarged) to fill the viewport space. This happens because the browser tries to fit the user coordinate system defined by the viewBox into the larger viewport, maintaining the aspect ratio unless specified otherwise. As a result, the image appears larger, and parts of it may even get cropped if they exceed the viewport’s boundaries.

As a result of the viewBox attribute using, the user coordinate system unit became equal to two units of the initial coordinate system. The scaling took place.

SVG crop using viewBox

The viewBox is a very useful tool for cropping images. The easiest way to crop the image is by using the min-x and min-y coordinates. Let’s look at how to crop the image to the left or right.

If you want to crop the image’s right part, set the min-x value with a negative number. When you set viewBox="-100 0 250 250", the viewBox shifts to the left, and the image gets cut off on the right because the viewBox defines which part of the SVG canvas is visible and how it’s mapped to the viewport.

What’s happening? -100 (min-x) shifts the starting point of the visible area 100 units to the left of the original (0, 0) origin. The viewBox now shows a 250-unit-wide area, starting from -100 and ending at 150 (since -100 + 250 = 150). You lose visibility of everything beyond 150 – this part is outside the defined viewBox and thus cut off.

The figure on the left shows the initial SVG viewport and user viewBox. The figure on the right illustrates the result of applying the viewBox attribute with a value of -100 for the min-x parameter.

Similarly, you can crop the image on the left by moving the viewBox to the right along the x-axis. The figure on the left shows the initial SVG viewport and user viewBox. The image on the right shows the result of applying the viewBox attribute with a value of 100 for the min-x parameter.

Conclusion

The viewBox attribute in SVG is a versatile tool that defines how graphics are scaled, positioned, and cropped within the viewport. By specifying four key parameters – min-x, min-y, width, and height – the viewBox controls the visible area of the SVG canvas and maps it to the viewport. This mapping enables seamless scaling, allowing SVG graphics to be resized without losing quality or distorting proportions.

Adjusting the viewBox parameters modifies the user coordinate system relative to the initial coordinate system. Changing min-x and min-y shifts the visible region, effectively cropping the content, while altering width and height scales the image either up or down to fit the viewport. When the viewBox is larger than the viewport, the content is scaled down, creating a zoom-out effect. Conversely, a smaller viewBox results in a zoom-in effect as the defined area is enlarged to fill the viewport.

The viewBox attribute was introduced as part of the SVG 1.0 specification by the W3C in 2001. Its primary purpose was to provide a mechanism for scaling and croping vector graphics across varying dimensions without losing quality – a core principle of the SVG format.

• To learn more and get SVG code examples for scaling, moving, rotating, and skewing SVG graphics using the SVG transform attribute, please go to the SVG Transformation article.
  

• Read the SVG Transformations – C# Examples article to get C# code examples for rotating, scaling, translating, and skewing SVG graphics using Aspose.SVG for .NET library.