Livsy Code

Why Your Vector PDF Looks Blurry

Greetings, traveler!

You add a vector PDF to an Xcode Asset Catalog, display it in your app, increase its size, and suddenly it does not look quite as sharp as you expected.

That seems strange. The source is a vector, so why does it behave like a low resolution bitmap?

The answer is in how Xcode processes vector assets. Adding a PDF to an Asset Catalog does not automatically mean that iOS will keep using its vector data at runtime.

How Xcode handles vector PDFs

Xcode has supported PDF assets in Asset Catalogs for years. By default, the PDF acts as a source from which Xcode generates rasterized representations for the display scales supported by the target platform.

Conceptually, the process looks like this:

Vector PDF
    ↓
Asset Catalog compiler
    ↓
Rasterized representations
    ↓
UIImage / SwiftUI Image

Apple described this behavior in its WWDC18 session on optimizing app assets. The advantage is that the device does not have to render an arbitrary PDF every time the image appears. Xcode does that work as part of asset compilation instead.

For an image displayed at its intended size, this usually works perfectly well. The difference becomes visible when you start making that image larger.

Preserve Vector Data

Asset Catalogs have a setting called Preserve Vector Data.

In the generated Contents.json, it appears as:

"properties": {
  "preserves-vector-representation": true
}

Apple’s Asset Catalog format documentation defines this property as a Boolean that tells Xcode to preserve the vector information of a PDF file.

You can enable it from the Attributes inspector for an image set in Xcode.

With the setting disabled, Xcode can use the PDF primarily as a build time source for rasterized images. With it enabled, Xcode also keeps the vector representation available to the system. That changes what happens when the image needs to be displayed beyond its natural size.

What happens when the image becomes larger

Suppose you have a PDF designed at 160 x 160 points. You add it to the Asset Catalog and later use it like this:

Image("terminal")
    .resizable()
    .frame(width: 320, height: 320)

Without preserved vector data, the system may need to scale a previously generated bitmap representation. At some point, the result can start looking soft. With Preserve Vector Data enabled, iOS can return to the original vector representation and rasterize the image for the larger size.

Preserving vector data does not mean that iOS renders the PDF from scratch every time the image appears. Apple explained that the system can still use the optimized prerendered bitmap at normal sizes. When the image grows beyond its natural size, the system can use the preserved PDF data to rasterize a representation suitable for that size.

So the behavior is closer to:

Normal size
    ↓
Use optimized bitmap representation

Larger size
    ↓
Use preserved vector data
    ↓
Rasterize for the required size

This is why the option exists separately from simply importing a PDF.

Single Scale is not the same thing

There is another Asset Catalog option that often causes confusion: Single Scale. When working with a vector PDF, you will commonly configure the image as a single scale asset instead of providing separate 1x, 2x, and 3x files.

That removes the need to maintain several source images, but it does not mean the vector information will necessarily remain available for arbitrary runtime scaling.

These are two separate decisions:

Single Scale

means that you provide one source asset instead of separate scale variants.

Preserve Vector Data

means that Xcode keeps the vector representation instead of relying only on generated raster representations.

Apple demonstrates this combination when discussing custom vector assets: switch the asset to Single Scale, provide the vector source, then enable Preserve Vector Data.

For scalable PDF assets, this is usually the configuration you want.

When Preserve Vector Data is useful

You do not need this setting just because a file happens to be a PDF. It becomes useful when the image may be displayed larger than its natural size.

A common example is a reusable illustration:

Image("terminal")
    .resizable()
    .scaledToFit()

Perhaps it is 80 points wide on one screen and 240 points wide on another. Keeping the vector representation gives the system a better source when it needs the larger version.

The same applies to layouts where the final size depends on available space:

Image("illustration")
    .resizable()
    .scaledToFit()
    .frame(maxWidth: .infinity)

The asset is no longer tied to one predictable point size.

Accessibility is another case. Apple’s documentation for the Large Content Viewer explicitly recommends using a PDF asset with Preserve Vector Data when an image needs to scale to a larger size.

Dynamic scaling is also important outside traditional iPhone layouts. In its visionOS guidance, Apple uses Single Scale together with Preserve Vector Data for custom graphics that need to remain sharp as the system changes their apparent size. Apple also notes that the setting is supported across Apple platforms.

When you probably do not need it

Consider a small icon that is designed for a specific size and always displayed at that size:

Image("close")
    .frame(width: 24, height: 24)

If the asset never becomes larger, preserving the PDF representation gives you little practical benefit for image quality.

The prerendered representation is already suitable for its intended size.

This is also why enabling the option for every PDF in a project should not be treated as a general rule. Apple introduced preserved vector data specifically for cases where assets need to grow beyond their natural size. The normal rasterization path avoids runtime work associated with rendering arbitrary vector content.

For fixed size icons, the default behavior can be completely appropriate. For assets whose size changes, preserving vector data makes much more sense.

A PDF file is not necessarily a vector image

There is one more problem worth checking before changing anything in Xcode. A .pdf extension does not guarantee that the content inside the file is actually vector based.

A PDF can contain vector paths:

PDF
├── paths
├── curves
├── fills
└── strokes

but it can also contain nothing more than a bitmap:

PDF
└── embedded raster image

For example, exporting a 512 x 512 PNG into a PDF container does not turn those pixels into vectors.

Preserve Vector Data cannot recover information that does not exist in the source. If your PDF contains an embedded bitmap, increasing the size will eventually expose the original raster resolution.

When an asset still looks blurry with Preserve Vector Data enabled, checking whether the PDF actually contains vector geometry should be one of the first debugging steps.

Do not solve this by exporting huge PDFs

Another common workaround is to export the asset at a much larger size. For a real vector PDF, that is usually unnecessary.

If an illustration is designed for a 160 x 160 point area, you do not need to create a 1024 x 1024 or 2048 x 2048 version just to make it look sharp on Retina displays.

The vector geometry already describes the shapes independently of pixel resolution.

Instead, keep the proper logical dimensions and configure the asset according to how it will be used:

– Vector PDF
– Single Scale
– Preserve Vector Data

Now the system has the original geometry available when a larger raster representation is required.

A practical rule

For a fixed size icon, you can usually leave Preserve Vector Data disabled. For a vector PDF that can become larger because of layout, accessibility, reusable components, or dynamic scaling, enable it.

A vector source file and a vector representation available at runtime are not automatically the same thing in an Asset Catalog. If your PDF looks surprisingly low resolution when resized, check Preserve Vector Data before asking the designer for a larger export.

It might be interesting: