Mac Catalyst

When you use Mac Catalyst to create a Mac version of your iPad app, you make your app available to a new audience while giving existing users the opportunity to enjoy it in a new environment.

Image of a MacBook Pro and an iPad Pro, both running the Ocean Journal app. The Mac version of the app uses two separate windows to display the content; the iPad version uses a split view.

For developer guidance, see Creating a Mac Version of Your iPad App.
Before You Start

Most iPad apps are great candidates for adaptation, but some rely on iPad features that don’t exist on a Mac. For example, if your app’s essential features require iPad capabilities like gyroscope, accelerometer, or rear camera, iOS frameworks like HealthKit or ARKit, or the app’s main function is something like navigation, it might not be suited for the Mac.

For apps that don’t require iPad-only features, the best way to ensure that your app will work well on a Mac is to make sure it works well on iPad. In particular, your app should:

Support multitasking. Apps that do a good job scaling the interface to support Split View, Slide Over, and Picture in Picture approach the ultimate goal of supporting the extensive window resizability that Mac users expect.
Support drag and drop. When you support drag and drop in your iPad app, you get the same support on the Mac for free.
Respond to keyboard shortcuts, including common macOS shortcuts. Even though a keyboard may not always be available to your iPad app, both iOS and macOS users appreciate using keyboard shortcuts to streamline their interaction with your app.

Plan Enhancements for Your Mac App

When you use Mac Catalyst to create a Mac version of your iPad app, you get automatic support for fundamental Mac features, such as:

System Preferences
Keyboard, trackpad, mouse, and Touch Bar input, including key focus and keyboard navigation
Window management
Rich text interaction, including copy and paste and contextual menus for editing
File management

In addition, many system-provided UI elements automatically convert from iOS to macOS. For example, you get macOS-appropriate versions of the following iOS-provided items:

Split view
File browser
Activity view
Form sheet
Contextual actions

To ensure that your app gives people a rich Mac experience, it’s essential to enhance this foundation and go beyond simply displaying your iOS UI in a macOS window. Before you dive in and update specific views and controls, become familiar with the main differences between the platforms so that you can create an app that feels at home on the Mac. (For comprehensive design guidance for macOS apps, see macOS Human Interface Guidelines.)

iOS and macOS each define design patterns and conventions for user interaction that are rooted in the different ways people use their devices. For example, iOS conventions such as swipe to delete, action sheet commands, and controls at the bottom of the screen are optimized for touch interactions on a handheld device. In a similar way, macOS conventions such as dedicated keys and keyboard shortcuts, menu commands, and controls at the top of the window are optimized for keyboard, mouse, and trackpad interactions and a separate display.

The conventions and design patterns that have the biggest impact on adaptation can be grouped into four key areas.

Navigation. Many iOS and macOS apps organize data in similar ways, but they use different controls and visual indicators to help people understand and navigate through the data. For specific guidance, see Adopt macOS App Structure and Navigation Conventions.

User input and interactions. Although both iPad and Mac accept user input from a range of devices — such as the Multi-Touch display, keyboard, mouse, and trackpad — touch interactions inform iOS conventions, whereas keyboard and mouse interactions originated the conventions for macOS. For related guidance, see Support macOS User Interactions.

Menus. Mac users are familiar with the persistent menu bar and expect to find all app commands in menu bar menus. iOS, on the other hand, doesn’t have a persistent menu bar, and iOS users expect to find app commands in the app’s UI. For related guidance, see Put App Commands into Menus.

Content scaling. Text in the macOS version of an iPad app looks the same as it does in iOS because SF fonts are available on both platforms. However, the baseline font size in iOS is 17 pt, whereas the most common font size in macOS is 13 pt. To ensure that your text and interface elements are consistent with the macOS display environment, iOS views automatically scale down to 77%. For related guidance, see Typography.

In addition to adopting macOS interaction and design conventions, you need to update your visual design and layout to take advantage of the wider Mac screen in ways that give macOS users a great experience. For example, you might:

Divide a single column of content and actions into multiple columns
Present an inspector UI next to the main content instead of within a popover
Simultaneously show two or more levels of an app’s hierarchy

For more guidance, see Visual Design Considerations.

Ideally, viewing your iPad app from the perspective of macOS design conventions can suggest ways to improve the iOS version, too. Although you want to make sure that each version remains true to the conventions of its platform, take this opportunity to revisit the design of your original app. Especially if your iPad app originated on iPhone, consider reassessing the ways you lay out views and controls to see if there are places where you can make better use of the large iPad screen.
Adopt macOS App Structure and Navigation Conventions

Well-designed app navigation reflects the structure of the data and supports the main purpose of the app in ways that follow the platform’s conventions. To help macOS users feel at home in your app, you need to translate the iOS navigation conventions to the equivalent macOS conventions.

Most iPad apps use either flat or hierarchical navigation, and some use a combination of both. Flat navigation presents areas of functionality or categories of data as peer groups that are always available. For example, Music and App Store use flat navigation to give people persistent access to high-level areas such as Library, For You, Browse, Today, and Games. Hierarchical navigation presents information in a tree-like organization through which people navigate by choosing one item per view until they reach their destination. In Settings, for example, people can customize text replacements by choosing General > Keyboards > Text Replacement.

Typically, iPad apps use the following UIKit controls to implement navigation:

Tab bar. A tab bar supports flat navigation by displaying top-level categories in a persistent bar at the bottom of the screen.
Page control. A page control displays dots at the bottom of the screen that indicate the position of the current page in a flat list of pages.
Split view. A split view enables hierarchical navigation by presenting items and functionality in a primary view (also called a master view) and a secondary view (also called a detail view). When people select an item in the primary view, a split view displays the content associated with that item in the secondary view.

If you use a tab bar in your iPad app, consider using a segmented control or the sidebar background style in a split view controller. Both items are similar to navigation conventions in Mac-style windows. To choose between these items, consider the following:

A segmented control and a tab bar both accommodate similar interactions — such as mutually exclusive selection — so a segmented control is a good alternative for a straightforward adaptation. A segmented control is ideal for iPad apps that don’t have a lot of hierarchy within each tab, because it can be paired with a sidebar to enable navigation within a tab.
A sidebar displays a list of top-level items, each of which can disclose a list of child items. Using a sidebar streamlines navigation because you can let people view each tab’s contents within the sidebar. Sidebars are a good choice for displaying app-defined or user-defined categories that don’t change very often. For example, the Following and Suggested categories in the News sidebar don’t change, even though people can change the items listed in each category.

You can also combine a segmented control and a sidebar in your app. For example, you might use a segmented control to contain the tabs, and a sidebar to display the contents of each tab. Regardless of how you adapt the tab bar, be sure to give people quick access to each tab’s content through the macOS View menu. To learn more about menus, see Put App Commands into Menus.

If you use a split view in your iPad app, macOS automatically translates it to a split view in the Mac version of your app. On both platforms, a master view is a good choice for presenting a list of items that can vary — such as the list of mailboxes in Mail — because it lets you include labels and icons and it supports sorting and filtering. However, if your content hierarchy is deeper than two levels, the middle levels between the master view and the current detail view aren’t visible in the Mac-style window. To ensure that people can retrace their steps, include a back button in the toolbar.

If you use a page control, or another way to enable lateral navigation, give people specific controls to view pages. If you support this type of lateral navigation, you can help people navigate through pages in your Mac-style window by displaying a Next/Previous button in the toolbar and adding navigation commands to a menu bar menu. For example, Stocks in macOS displays both a Back button in the toolbar and Next Story and Previous Story commands in the View menu.

If you support multiple windows in your iPad app, you get support for multiple windows in the macOS version, too. In addition, many macOS apps let people open documents or other content in a new tab instead of in a new window. For example, people can open a different webpage per tab in a Safari window or a different file system location per tab in a Finder window. When people use System Preferences to prefer tabs over windows, the system dynamically adds the relevant menu items to an app’s menus, such as View > Show Tab Bar and Window > Show Next Tab.
Support macOS User Interactions

Selection persistence is a fundamental difference in user interaction between iOS and macOS. Because many macOS users expect to control apps and the system using only the keyboard, the selected state of objects must persist so that people can use one sequence of key presses to select an object and a second sequence to act upon it. In contrast, iOS users expect to act upon an object without selecting it first, so objects don’t need to retain their selected state. As a general rule, iOS apps don’t tend to be optimized for keyboard interactions.

Here are some ways that different interaction conventions can affect the user experience:

macOS users often want Next and Previous buttons in place of iPad or trackpad gestures such as swiping among pages.
On a Mac, people expect to use the Delete key or select a Delete command in a menu, so displaying a Delete button in the UI is usually unnecessary.
iOS users are accustomed to pulling down on a view to refresh the contents. In contrast, Mac users expect to use a menu command, such as Check for New Content.

As you translate iPad user interaction patterns to Mac interactions, focus on letting people manipulate objects in ways that adhere to platform conventions.
Keyboard Input

Be prepared to support keyboard conventions that let people change a persistent selection by using arrow keys or by pressing letter and number keys.

If it makes sense in your app, take advantage of the fact that Mac users can easily use the keyboard and the mouse or trackpad at the same time.

If you implement UIKeyCommand in your iPad app to define keyboard sequences for commands, the macOS version of your app translates these shortcuts to the menus. For example, you should map each major view area, such as each tab, to the keyboard shortcuts ⌘1, ⌘2, and so on for display in the View menu of the macOS version of your app.

If there’s a Delete button in the UI of your iPad app, consider removing it from the macOS version and letting people use the Delete key or the app’s Edit > Delete menu command instead.
Gestures

When your iPad app runs in macOS, most gestures convert automatically. For example:
iPad gesture… Translates to mouse interaction
Tap Left or right click
Touch and hold Click and hold
Pan Left click and drag
iPad gesture… Translates to trackpad gesture
Tap Click
Touch and hold Click and hold
Pan Click and drag
Pinch Pinch
Rotate Rotate

DEVELOPER NOTE
The two touches in the pinch and rotate gestures get sent to the view under the pointer, not the view under each touch.
Put App Commands into Menus

On a Mac, the menu bar at the top of the screen gives people a consistent location for commands that control both apps and the system. The menu bar contains the standard and custom menus supplied by the current app, in addition to the Apple menu, which lists system-level commands that are always available. Mac users expect every macOS app to make all its commands available in the menu bar.

DEVELOPER NOTE
You must use UICommand to represent each command in your iPad app so that these commands can be put into macOS menu bar menus. To support keyboard shortcuts for commands, use UIKeyCommand.

Because iPad apps use controls to display commands in the main UI, finding a logical and intuitive menu bar location for every app command is a key part of the adaptation process.

To design the menu bar menus for the macOS version of your app, start by listing all the actions that people can perform and grouping them into the categories defined by the standard menu bar menus. For example:

App Name
File
Edit
View
Window
Help

NOTE
Most macOS apps include a View menu and a Window menu. Although these menus may seem similar, they have different purposes. People use the View menu to customize the appearance of app windows and to move among different functional areas, whereas they use the Window menu to navigate, organize, and manage the collection of windows in an app. To learn more, see Menu Bar Menus.

If some of the actions on your list don’t make sense in the standard menu bar menus, you might need to add a custom menu. Mac apps often add a custom menu bar menu for commands that are associated with either a core app object or a core app workflow. For example, Mail in macOS uses the Message and Mailbox menus to list commands that operate on these fundamental app objects. In contrast, Keynote uses the Arrange menu to list commands associated with the core workflow of arranging objects in a slide deck.

After you group your app’s actions into menus, you need to order the items in each menu in a way that makes sense. Each standard menu defines a recommended order for items, so it’s important to follow this order for the items that you support. For example, Mac users expect the File menu to present items in this order:

New...
Open...
Open Recent
Close

In a custom menu bar menu, you should order the items according to importance, frequency of use, or another scheme that makes sense in your app. Menu bar menus can also contain submenus and separators that help group items in logical ways. To learn more about these menu components, see Menu Anatomy.

Also, it’s important to support keyboard shortcuts for all common commands in your menus so that both Mac users and iPad users who use keyboards can benefit. In addition to enabling the shortcuts for standard menu items, you can also define shortcuts for custom items. If custom menu items make sense in your app, be sure to review the guidance for creating custom keyboard shortcuts in Defining Keyboard Shortcuts.
Contextual Menus

Contextual menus help people discover the actions that they can perform on an object without opening a menu bar menu. If you support context menus in your iPad app, the system automatically converts them to contextual menus in the macOS version of your app.

To give Mac users the best experience, look for additional places to support contextual menus. For example, if there are common actions that people can perform on an object in your app, add a contextual menu that lists these actions. You can also add a contextual menu to a view that represents an object — for example, folder objects in the Finder support contextual menus that offer actions like Open in New Tab, Rename, and Duplicate.
Visual Design Considerations

To help your iPad app look great when it runs in macOS, take into account the platform differences in the following areas of visual design.
Layout

Mac users expect to resize app windows to just about any size from full screen to as small as the app permits. To support this type of infinite resizability — and to take advantage of the Mac’s wider display — use the regular width and regular height size classes and consider reflowing elements in your window’s content area to a side-by-side arrangement when necessary.

As much as possible, adopt a top-down layout. macOS apps place the most important actions and content near the top of the window. If your iPad app provides controls in a toolbar or navigation bar, put these controls in the window toolbar of the macOS version of your app.

Consider moving controls from the main UI of your iPad app to the toolbar of your macOS window. Also, list the commands associated with these controls in the menus of your macOS app’s menu bar.

NOTE
In macOS, a toolbar button is always visible, but the current context might make it unavailable; in iOS, a toolbar button is always available, but the current context might remove it from the toolbar. For example, if your iPad app includes a toolbar button that works in only one tab, the macOS version displays the button as unavailable in all other tabs. To avoid confusing people, it can work better to use a “gear” button in the toolbar instead, because the items in a gear button’s menu differ depending on the current app section.

Relocate buttons from the left or right edge of the screen. On iPad, placing buttons on the middle left or middle right screen edges can help people reach them, but on a Mac, this ergonomic consideration doesn’t apply. You may want to relocate controls to the top or bottom edge of the content area or put them in the toolbar of your macOS window.
Color

Use the system selection color on both platforms. In general, iOS apps define the colors used to tint buttons and to indicate selection, but in macOS, people expect to use System Preferences to choose the selection and button colors they want.

The dynamic system colors designed for iOS backgrounds automatically map to appropriate macOS equivalents, as shown below.
iOS color Equivalent macOS color
systemBackground selectedContentBackgroundColor
secondarySystemBackground windowBackgroundColor
tertiarySystemBackground selectedContentBackgroundColor (overlaid with quaternaryLabelColor)
systemGroupedBackground windowBackgroundColor
secondarySystemGroupedBackground selectedContentBackgroundColor
tertiarySystemGroupedBackground selectedContentBackgroundColor (overlaid with quaternaryLabelColor)

Other semantically defined iOS colors — such as the system colors and the label and separator colors — map to similarly named macOS colors. For guidance, see System Colors (macOS) and Dynamic System Colors (macOS).

Don’t tint buttons in table rows. In your iPad app, you use a tint to show that buttons in table rows are active, but in macOS, tinted buttons in table rows look out of place.
Typography

Although the automatic scaling performed by the system gives good results without requiring you to specify different font values on both platforms, you might not get the best results in every situation.

Make sure small type is legible on the Mac. Be prepared to increase some of the smallest font sizes you use in your iPad app so that all text remains legible in the macOS version. Also, note that Dynamic Type is not supported in macOS.
Custom Icons and Glyphs

Create a macOS version of your app icon. Great macOS app icons are noticeably different from great iOS app icons — for example, macOS icons can have nonrectangular shapes and are often skewed and rotated. By default, macOS applies a drop shadow to your iOS app icon so that it feels more at home on a Mac, but it’s better to design a Mac-specific version of your app icon. To learn more about how to approach the design of a macOS app icon, see App Icon.

Create platform-specific glyphs, if necessary. If your iPad app uses custom glyphs that reference the platform in some way, create new glyphs that feel at home on the Mac. Xcode provides a separate asset catalog you can use in your iPad app for macOS-specific glyphs.
Preferences

If you supply app settings that appear in the iOS Settings app, macOS automatically displays these items in a preferences window in the Mac version of your app. By default, macOS adds a toolbar button to the preferences window for each item in your iOS settings, giving it the standard system preferences icon and the title you used for the item’s view in the Settings app.

As Mac users expect, your preferences window appears when they choose the Preferences menu item in your app menu. However, there are a few ways you can refine the display of your settings items and make your app’s preferences experience feel more Mac-like.

Customize the icon for each item’s toolbar button. Because macOS automatically uses the standard system preferences icon for your settings items, people will have to read each toolbar button’s title to distinguish among multiple items. To improve this experience, supply a custom icon for each settings item.

Make switch controls easier for macOS users to understand. Unlike iPad apps, a macOS app often displays a confirmation alert when someone uses a switch to make changes in System Preferences. In addition, a switch in iOS Settings can include a small amount of text that provides more information about how the switch affects the user experience. In the Mac version of your app, you can provide a brief description to accompany a macOS switch and you can specify content to display in a confirmation alert when people use it to change a setting. For developer guidance, see Displaying a Preferences Window.