The SVG viewBox explained, with preserveAspectRatio
How the viewBox attribute maps your drawing to the screen, how to shift and scale the coordinate system, and how preserveAspectRatio fits it into any box.
The viewBox attribute is the most common source of confusion for people new to SVG, and also the feature that makes SVG scale so well. Once you see it as a window onto a coordinate grid, it stops being mysterious.
Two sizes, not one
An <svg> element has two separate ideas of size.
- The viewport: how big the graphic is on the page. This comes from the
widthandheightattributes, or from CSS. MDN says these set the displayed size of the viewport, not the size of the coordinate system, and that both default toauto. - The user coordinate system: the grid your shapes are drawn on. This is what
viewBoxdefines.
The viewBox has four numbers: min-x min-y width height. MDN separates them with whitespace and notes that commas also work. The rectangle they describe is mapped onto the viewport. If the two have the same aspect ratio, the whole viewBox fills the viewport exactly. In SVG 2 terms, the viewBox maps a rectangle in user space onto the viewport.
The width and height inside the viewBox are in user units, not pixels. MDN also warns that a width or height of zero or less disables rendering of the element.
A worked example
Take a circle with r="40". Whether it looks big or small depends entirely on the grid.
<svg viewBox="0 0 100 100"> <!-- circle fills most of the box -->
<svg viewBox="0 0 400 400"> <!-- same circle looks much smaller -->
MDN makes the same point with three SVGs: the same content in viewBox="0 0 100 100", "0 0 10 10" and "-5 -5 10 10". A percentage-sized <rect> fills the viewport in all of them, while a circle with r="4" is small in the 100 by 100 case and large in the 10 by 10 cases, because its radius is in user units.
Edit the viewBox below. Change the last two numbers to 400 240 and watch the same drawing shrink. Change them to 100 60 and it grows.
The shapes never changed. Only the window onto them did. This is why one drawing can serve any display size: write the shapes once, and let viewBox and the container decide the scale.
Moving the origin
The first two numbers, min-x and min-y, set which point is at the top-left of the window. MDN notes that a negative origin shifts the coordinate system so that (0, 0) no longer sits at the top-left corner. Its example viewBox="-5 -5 10 10" puts the origin in the center.
Centering the origin is handy for anything symmetric, such as a clock face, a radar, or a rotating logo, because positions become simple: a shape at 0 0 is in the middle.
Here every shape uses cx="0" cy="0", and the viewBox starts at -100 -60. Try changing the first number to 0. The drawing moves toward the lower right, because the window now starts at the origin.
When the shapes and the box disagree: preserveAspectRatio
If the viewBox and the viewport have different aspect ratios, the browser must decide what to do with the extra space or the overflow. That is the job of preserveAspectRatio. MDN gives the syntax as an align value plus an optional meet or slice:
preserveAspectRatio="<align> [<meet or slice>]"
The default is xMidYMid meet. Here is what the parts mean:
meet(default) scales as large as possible while keeping the entireviewBoxvisible. If the ratios differ, part of the viewport is left empty.slicescales as small as needed to fully cover the viewport, so part of theviewBoxis cropped.nonedoes not preserve the aspect ratio. Content is stretched non-uniformly to match the viewport, which distorts circles into ellipses. Anymeetorslicekeyword is ignored.- The align part, from
xMinYMinthroughxMaxYMax, chooses which edges or centers line up.xMidYMidcenters both ways, andxMinYMinpins to the top-left.
MDN adds that without a viewBox, the attribute has no effect on SVG scaling, except on <image>.
The playground shows a 100 by 100 viewBox inside a wide, short box (200 by 60). Change meet to slice, then to none, and watch what happens. Try xMinYMin as well.
With meet, the full square is visible, scaled to the height of the box, with empty space on the sides. With slice, the square fills the width, and the top and bottom are cropped. With none, the circle becomes an ellipse.
Practical rules
Always include a viewBox on SVGs you want to scale. Without one, the shapes use pixel-like units and will not resize with their container. The viewBox has no default value, per MDN, so it is not added for you.
Let CSS control the size. A common pattern is viewBox in the markup and width: 100%; height: auto in CSS, so the graphic fills its column and keeps its shape. See responsive SVG.
Draw to a convenient grid. A viewBox of 0 0 24 24 is common for icons, and 0 0 100 100 is easy to reason about. Choose numbers that make your coordinates simple.
Leave room for strokes. Strokes are centered on the edge of a shape, so half the stroke width falls outside the geometry. If a shape touches the edge of the viewBox, the outer half of the stroke can be clipped. Pad the viewBox, or pull the shape inward.
Do not mix up viewBox with width and height inside it. The first pair of numbers are positions, the second pair are sizes. It is easy to read 0 0 200 120 as “the box is 200 by 120 pixels”. It is a 200 by 120 grid, shown at whatever size the element ends up.
Common mistakes
- Forgetting the
viewBox, then wondering why the graphic is cropped or will not scale. Add it, matching the extent of your drawing. - Setting
preserveAspectRatio="none"on logos or icons. Distortion is rarely what you want. Reserve it for decorative backgrounds, charts that should stretch, or textures. - Expecting
viewBoxto resize the element on the page. It only maps the grid to whatever size the element already has.
Where this leads
The viewBox is the foundation for everything else. Once you control the grid, paths become easier to write, transforms behave predictably, and masks and clipping line up the way you expect. For a broader introduction, see what is SVG.
Sources
Checked against these references on 2026-11-21.