Document Icons

A document icon represents a file that uses a document type your app supports. Traditionally, a document icon looks like a piece of paper with its top-right corner folded down. This distinctive appearance helps people distinguish documents from apps and other content, even when icon sizes are small.

If you don’t supply a document icon for a file type you support, macOS 11 creates one for you by compositing your app icon and the file’s extension onto the canvas. For example, Preview uses a system-generated document icon to represent JPG files.

An image of the Preview document icon for a JPG file.

NOTE If your app runs in earlier versions of macOS, you should supply a legacy document icon. If you let earlier versions of macOS generate a document icon for you, you get different results in different versions. Specifically, macOS 10.15 creates a document icon by compositing your app icon, but not the file extension; macOS 10.14 and earlier use a generic document background if you don’t supply any assets.

If your app opens one or more custom file types, you can create custom document icons to represent them. For example, Xcode uses custom document icons to help people distinguish documents for projects, AR objects, and Swift code files.

Image of a document icon for an Xcode project.

Image of a document icon for an AR object.

Image of a document icon for a Swift file.

To create a custom document icon, you can supply any combination of background fill, center image, and text. macOS 11 layers, positions, and masks these elements as needed and composites them onto the familiar folded-corner icon shape.

A square canvas that contains a grid of pink lines and a jagged white EKG line that runs horizontally across the middle. The pink grid gets lighter in color toward the bottom edge.

Background fill

A solid pink heart.

Center image

The word heart in all caps.


A custom document icon that displays the pink heart and the word heart on top of the pink grid and white EKG line.

macOS 11 composites the elements you supply to produce your custom document icon.

Apple Design Resources provides a template you can use to create a custom background fill and center image for a document icon. As you use this template, follow the guidelines below.

Design simple images that clearly communicate the document type. Whether you use a background fill, a center image, or both, prefer uncomplicated shapes and a reduced palette of distinct colors. Your document icon can display as small as 16x16 pt, so you want to create designs that remain recognizable at every size.

Designing a single, expressive image for the background fill can be a great way to help people understand and recognize a document type. For example, Xcode and TextEdit both use rich background images that don’t include a center image.

Image of an Xcode project document icon.

Image of a TextEdit rich text document icon.

Consider reducing complexity in the small versions of your icon. Icon details that are clear in large versions can look blurry and be hard to recognize in small versions. For example, to ensure that the grid lines in the custom heart document icon remain clear in intermediate sizes, you might use fewer lines and thicken them by aligning them to the reduced pixel grid. In the 16x16 px size, you might remove the lines altogether.

Pixelated image of the heart document icon. The grid, the EKG line, the heart shape, and the word heart are visible but blurry.

The 32x32 px icon has fewer grid lines and a thicker EKG line.

Pixelated image of the heart document icon, in which only the blurry heart shape and EKG line are visible.

The 16x16 px @2x icon retains the EKG line but has no grid lines.

Pixelated image of the heart document icon, in which only the blurry heart shape is visible.

The 16x16 px @1x icon has no EKG line and no grid lines.

Avoid placing important content in the top-right corner of your background fill. The system automatically masks your image to fit the document icon shape and draws the white folded corner on top of the fill. Create a set of background images in the sizes listed below.

  • 512x512 pt (1024x1024 px @2x)
  • 256x256 pt (512x512 px @2x)
  • 128x128 pt (256x256 px @2x)
  • 32x32 pt (64x64 px @2x)
  • 16x16 pt (32x32 px @2x)

If a familiar object or glyph can convey a document’s type or its connection with your app, consider creating a center image that depicts it. Design a simple, unambiguous image that’s clear and recognizable at every size. The center image measures half the size of the overall document icon canvas. For example, to create a center image for a 32x32 pt document icon, use an image canvas that measures 16x16 pt. You can provide center images in the following sizes:

  • 256x256 pt (512x512 px @2x)
  • 128x128 pt (256x256 px @2x)
  • 32x32 pt (64x64 px @2x)
  • 16x16 pt (32x32 px @2x)

Define a margin that measures about 10% of the image canvas and keep most of the image within it. Although parts of the image can extend into this margin for optical alignment, it’s best when the image occupies about 80% of the image canvas. For example, most of the center image in a 256x256 pt canvas should fit in an area that measures 205x205 pt.

Diagram of the solid pink heart shape within blue margins that measure 10 percent of the canvas width.

Specify a succinct term if it helps people understand your document type. By default, the system displays a document’s extension at the bottom edge of the document icon, but if the extension is unfamiliar you can supply a more descriptive term. For example, the document icon for a SceneKit scene file uses the term scene instead of the file extension scn. The system automatically scales the extension text to fit in the document icon, so be sure to use a term that’s short enough to be readable at small sizes. By default, the system capitalizes every letter in the text.

Image of a SceneKit scene document icon.