Skip to content

Custom Folder Icons with macOS Uniform Type Identifiers

Did you know that you have a custom icon on folders created from your Xojo app? Read on to learn more!

Uniform Type Identifiers (UTIs) are one of the many often misunderstood parts of building native macOS apps. While they’re not just for specifying file types, that’s what I’m going to focus on today. First, a little background:

Uniform Type Identifiers are the successor to Apple’s Creator and Type codes that were used in MacOS Classic 15+ years ago. Back then, every mac application had a creator code (Four characters) which had to be unique and therefore registered with Apple for use in an app. Then, each file type that you wanted to create also needed a unique code. Common types were TEXT for text files, APPL for applications and RTFd for RTF documents. This was their attempt to keep from having file extensions and while it “worked” there were some severe limitations.

When MacOS X appeared on the scene, file extensions became a necessity again what with their BSD Unix underpinnings and when 10.6 was released, Apple revisited their position on exposing users to extensions again. (Don’t get me wrong, macOS does an excellent job of hiding extensions from users that don’t need to see them and exposing them to users who do. As an old-school user, I’m grateful for that.) This meant that they had an opportunity to update their antiquated system for application and file type association. 

At first glance, wrapping your head around UTIs may seem a little daunting, but let’s break it down for you:

  1. First, your application needs a valid Bundle Identifier. This setting is found in the macOS build target settings and its value is in reverse domain name format. While it’s not required, I suggest you use your personal or company domain name to form this identifier. If your domain was, the bundle identifier would look like com.example.myappname.
  2. Next, you’ll need to add a special kind of File Type to your app. Add a “File Type Set” to your project and add a new type by clicking the + button at the top of the editor.
    1. Give your type a name like “FolderWithIcon”.
    2. Assign a UTI Identifier. This must start with the same reverse name that you used for your bundle identifier when making file types for something that your app creates. For example: com.example.myfolder. This value must be unique within your app.
    3. Add “public.folder” to the Conforms To field. This value represents the other type(s) of files that your type is associated with. For more information see Apple’s list of public identifiers.
    4. Set the Extensions field to “.myfolder”. This value must be unique within your app.
    5. Set UTI Type to Exported
    6. Add a unique folder icon to your file type.
  3. In places where you want to have these custom folders all you have to do now is add the extension and then hide the extension from the user:
    Dim f As FolderItem = SpecialFolder.Desktop.Child("Test.myfolder")
    f.ExtensionVisible = False
  4. Build your app (running won’t always work). Note: macOS reads these specs right from the latest version of your app and caches them, so if you need to update your icon you’ll need to at least increase your app’s non-release version number.

That’s all there is to it! From now on, when you create a folder in your app, it’ll get your snazzy new icon!