If you have ever exported an icon that stubbornly refused to resize, or opened one with a mysterious slab of empty space around it, you have met the viewBox, whether you knew its name or not. It is the attribute that makes SVG scalable, and it is also the attribute people copy around without understanding, which is why it causes so many small, baffling layout problems. This guide explains what it does with actual numbers, then works through the specific failures it causes and how to fix each one.
None of it is hard once the core idea lands, and the core idea is genuinely small.
What the viewBox actually is
The viewBox defines the internal coordinate system of the SVG, the invisible sheet of graph paper the shapes are drawn on. It tells the renderer: here is the region of coordinate space I want you to look at, now fit that region into whatever size I happen to be displayed at. Because the shapes are positioned within that coordinate space, and the viewBox maps that space onto the rendered box, changing the display size simply rescales the entire drawing to match.
That mapping is the whole mechanism behind "scalable" in Scalable Vector Graphics. It is not that vector shapes are magically resolution-independent by themselves; it is that the viewBox gives the renderer a rule for stretching the coordinate space to any output size. The what is an SVG file guide covers the vector side; the viewBox is how that vector content is placed on screen.
The syntax: four numbers
The attribute takes four numbers in a specific order:
viewBox="min-x min-y width height"
- min-x, min-y set the top-left corner of the region, in user units. These are usually
0 0. - width, height set how many user units wide and tall that region is.
So viewBox="0 0 24 24" means a 24-by-24 coordinate space with its origin in the top-left. An icon whose shapes use coordinates between 0 and 24 fills that space exactly. This is why so many UI icons are built on a 24-unit grid, a convention the icon sizes guide gets into. The critical thing to internalise is that these units are not pixels. They are abstract user units that get scaled to whatever the rendered size turns out to be.
viewBox versus width and height
These are two different jobs that get confused constantly:
- The viewBox is the internal coordinate space, what the numbers inside your shapes mean.
- The width and height attributes, or CSS width and height, are the actual rendered size on the page.
Set viewBox="0 0 24 24" and width="96", and the 24-unit drawing is scaled up four times to render at 96 pixels, staying perfectly sharp. Change the width to 16 and the same drawing shrinks to fit. The shapes themselves never change; only the mapping from coordinate space to output size does. For icons, the best practice that follows from this is to set the viewBox once and control the display size with CSS rather than hard-coded attributes, so a single file works at every size, which the using SVG icons guide demonstrates.
Why your SVG will not scale
Here is the classic bug: an exported icon ignores your CSS width, or refuses to shrink, or carries strange empty space around it. Around nine times in ten, the SVG either has no viewBox or has the wrong one.
With no viewBox, the SVG falls back to using its own width and height as the coordinate system, so it has no rule for remapping itself when you resize it with CSS. Instead of scaling, it clips or leaves whitespace. The fix is to add a viewBox that matches the artwork's bounds: if the icon's shapes span 0 to 32 in both directions, set viewBox="0 0 32 32", then remove any fixed width and height or override them in CSS. If the problem is instead a large empty margin around the icon, the viewBox is bigger than the art, for example the drawing sitting in the middle of a 512-unit box, and the fix is to tighten the viewBox down to the artwork's bounding box.
preserveAspectRatio: fit, crop, align
When the viewBox's aspect ratio does not match the rendered box, say a square viewBox inside a wide container, preserveAspectRatio decides what happens. Its format is preserveAspectRatio="<align> <meetOrSlice>", and the default is xMidYMid meet.
- meet scales the graphic so the whole viewBox fits inside the box, leaving empty space around it, like letterboxing. Nothing is cropped.
- slice scales so the viewBox covers the entire box and crops whatever overflows, the same idea as
background-size: cover. - The align value, such as
xMidYMidorxMinYMin, decides where the graphic sits when there is spare space, or which edge gets cropped under slice.
This attribute is the source of "my SVG is cropped", usually from slice or a wrong viewBox, and "my SVG is off-centre", from an align value other than Mid. For the vast majority of icons the default is exactly right and you never touch it; you reach for it deliberately on banners and full-bleed background SVGs.
Fixing a broken viewBox
A checklist for the common symptoms:
- The icon will not resize: add a viewBox matching the art, and drop the hard-coded width and height.
- There is a big empty margin around the icon: shrink the viewBox to the art's bounding box. In Inkscape, resize the document to the drawing; in Illustrator, fit the artboard to the artwork.
- The icon is cropped: the viewBox is smaller than the art, or preserveAspectRatio is set to slice. Widen the viewBox, or switch to meet.
- The icon looks stretched: you set width and height to a different ratio than the viewBox and forced a non-uniform scale. Match the ratio, or let one dimension be automatic.
The general principle: never try to fix a scaling problem by editing every coordinate in the file. Fix the viewBox, which rescales everything at once, and then run the file through an optimiser to tidy it up.
Frequently asked questions
Confused by the path strings inside your SVG as well? See SVG path data.
Choosing what display size to render icons at? The icon sizes guide covers the standard scale.