cardinale/swift-front
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
swift-front/data/categories/inputs.json
T
Anthony Cardinale 34bd90e30d Initial release: swift-front skill with Apple HIG integration 
Combines frontend-design aesthetics with swiftui-pro correctness,
grounded in Apple's Human Interface Guidelines (134 articles).

Includes curated HIG reference files for typography, color, layout,
materials, motion, icons, and components, plus full HIG JSON data
for deep lookups.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-25 07:52:07 -04:00

4476 lines
214 KiB
JSON
Raw Permalink Blame History

This file contains invisible Unicode characters
This file contains invisible Unicode characters that are indistinguishable to humans but may be processed differently by a computer. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
{
"metadata": {
"source": "Apple Human Interface Guidelines",
"source_url": "https://developer.apple.com/design/human-interface-guidelines/",
"generated_at": "2026-03-24T10:09:01.952605+00:00",
"article_count": 134,
"format_version": "1.0",
"purpose": "Agent-readable reference for designing Swift/SwiftUI applications following Apple HIG",
"category": "inputs"
},
"name": "Inputs",
"articles": [
{
"title": "Action button",
"url": "https://developer.apple.com/design/human-interface-guidelines/action-button",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "On a supported device, people can use the Action button to run App Shortcuts or access system-provided functionality, like turning the flashlight on or off. On Apple Watch Ultra, the Action button supports activity-related actions, including workouts and dives."
},
{
"type": "paragraph",
"text": "A person chooses a function for the Action button when they set up their device; later, they can adjust this choice in Settings. When someone associates an App Shortcut with the Action button, pressing the button runs the App Shortcut similarly to using their voice with Siri or tapping it in Spotlight."
},
{
"type": "paragraph",
"text": "When designing your app or game, think of the Action button as another way for someone to quickly access a function that they use on a regular basis."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Support the Action button with a set of your app’s essential functions. For example, if your cooking app includes an egg timer, a “Start Egg Timer” action might be one that people want to initiate when they press the Action button. You don’t need to offer an App Shortcut that opens your app, because the system provides this function already. Your app icon, widgets, and Apple Watch complications give people other quick ways to open your app. For additional guidance, see App Shortcuts."
},
{
"type": "paragraph",
"text": "For each action you support, write a short label that succinctly describes it. People see your labels when they visit Settings to configure the Action button’s behavior. Create labels that use title-style capitalization, begin with a verb, use present tense, and exclude articles and prepositions. Keep labels as short as possible, with a maximum of three words. For example, use “Start Race” instead of “Started Race” or “Start the Race.”"
},
{
"type": "paragraph",
"text": "Prefer letting the system show people how to use the Action button with your app. When you support the Action button, the system automatically helps people configure it to initiate one of your app’s functions. Avoid creating content that repeats the guidance offered in Settings for the Action button, or other usage tips the system provides."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iPadOS, macOS, tvOS, or visionOS."
}
]
},
{
"heading": "iOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Let people use your actions without leaving their current context. When possible, make use of lightweight multitasking capabilities like Live Activities and custom snippets to provide functionality without opening your app. For example, the “Set Timer” action doesn’t launch the Clock app; it prompts people to set a duration for the timer, and then launches a Live Activity with the countdown."
}
]
},
{
"heading": "watchOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In watchOS, a person can assign the Action button’s first press to drop a waypoint, start a dive, or begin a specific workout. Beyond a single button press, the Action button also supports secondary actions like marking a segment or transitioning to the next modality during a multi-part workout."
},
{
"type": "paragraph",
"text": "Consider offering a secondary function that supports or advances the primary action people choose. People often use the Action button without looking at the screen, so a subsequent button press needs to flow logically from the first press, while also making sense in the current context. If your app supports workout or dive actions, consider designing a simple, intuitive secondary function that people can easily learn and remember. Consider carefully before you offer more than one secondary function, because doing so can increase people’s cognitive load and make your app seem harder to use."
},
{
"type": "paragraph",
"text": "Prefer using subsequent button presses to support additional functionality rather than to stop or conclude a function. If you need to let people stop their main task — as opposed to pausing the current function — offer this option within your interface instead."
},
{
"type": "paragraph",
"text": "Pause the current function when people press the Action button and side button together. The exception is in a diving app where pausing a dive may be dangerous to the diver, causing them to lose track of their depth or not understand how long they’ve been underwater. Unless pausing the current function results in a negative experience, be sure to meet people’s expectations by letting them pause their current activity when they press both buttons at the same time."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Workouts"
},
{
"type": "paragraph",
"text": "Digital Crown"
},
{
"type": "paragraph",
"text": "App Shortcuts"
},
{
"type": "paragraph",
"text": "Live Activities"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"September 12, 2023",
"Updated to include guidance for iOS."
],
[
"September 14, 2022",
"New page."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "App Shortcuts",
"url": "/design/human-interface-guidelines/app-shortcuts"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/action-button#Best-practices"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/action-button#Platform-considerations"
},
{
"title": "iOS",
"url": "/design/human-interface-guidelines/action-button#iOS"
},
{
"title": "Live Activities",
"url": "/design/human-interface-guidelines/live-activities"
},
{
"title": "watchOS",
"url": "/design/human-interface-guidelines/action-button#watchOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/action-button#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/action-button#Related"
},
{
"title": "Workouts",
"url": "/design/human-interface-guidelines/workouts"
},
{
"title": "Digital Crown",
"url": "/design/human-interface-guidelines/digital-crown"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/action-button#Change-log"
}
],
"image_count": 0
},
{
"title": "Apple Pencil and Scribble",
"url": "https://developer.apple.com/design/human-interface-guidelines/apple-pencil-and-scribble",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Apple Pencil is a versatile, intuitive tool for iPad apps that offers pixel‑level precision when jotting notes, sketching, painting, marking up documents, and more. Scribble lets people use Apple Pencil to enter text in any text field through fast, private, on-device handwriting recognition."
},
{
"type": "paragraph",
"text": "For details on Apple Pencil features and compatibility, see Apple Pencil."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Support behaviors people intuitively expect when using a marking instrument. Most people have a lot of experience with real-world marking tools, and this knowledge informs their expectations when they use Apple Pencil with your app. To provide a delightful experience, think about the ways people interact with nondigital pencils, pens, and other marking instruments, and proactively support actions that people may naturally attempt. For example, people often want to write in the margins of documents or books."
},
{
"type": "paragraph",
"text": "Let people choose when to switch between Apple Pencil and finger input. For example, if your app supports Apple Pencil for marking, also ensure that your app’s controls respond to Apple Pencil so people don’t have to switch to using their finger to activate them. In this scenario, a control that doesn’t support Apple Pencil input might seem to be unresponsive, giving the impression of a malfunction or low battery. (Scribble only supports Apple Pencil input.)"
},
{
"type": "paragraph",
"text": "Let people make a mark the moment Apple Pencil touches the screen. You want the experience of putting Apple Pencil to screen to mirror the experience of putting a classic pencil to paper, so it’s essential to avoid requiring people to tap a button or enter a special mode before they can make a mark."
},
{
"type": "paragraph",
"text": "Help people express themselves by responding to the way they use Apple Pencil. Apple Pencil may sense tilt (altitude), force (pressure), orientation (azimuth), and barrel roll. Use this information to affect the strokes Apple Pencil makes, such as by varying thickness and intensity. When responding to pressure, keep things simple and intuitive. For example, it feels natural to affect continuous properties — such as ink opacity or brush size — by varying the pressure."
},
{
"type": "paragraph",
"text": "Altitude"
},
{
"type": "paragraph",
"text": "Pressure"
},
{
"type": "paragraph",
"text": "Azimuth"
},
{
"type": "paragraph",
"text": "Provide visual feedback to indicate a direct connection with content. Make sure Apple Pencil appears to directly and immediately manipulate content it touches onscreen. Avoid letting Apple Pencil appear to initiate seemingly disconnected actions, or affect content on other parts of the screen."
},
{
"type": "paragraph",
"text": "Design a great left- and right-handed experience. Avoid placing controls in locations that may be obscured by either hand. If there’s a chance controls may become obscured, consider letting people reposition them."
}
]
},
{
"heading": "Hover",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use hover to help people predict what will happen when Apple Pencil touches the screen. For example, as people hold Apple Pencil above the screen, a hover preview can show the dimensions and color of the mark that the current tool can make. As much as possible, avoid continuously modifying the preview as people move Apple Pencil closer or farther from the screen. A preview that changes according to height is unlikely to clarify the mark Apple Pencil will make, and frequent visual variations can be very distracting to people."
},
{
"type": "paragraph",
"text": "Avoid using hover to initiate an action. Unlike tapping a button or marking the screen, hovering is a relatively imprecise motion that doesn’t require people to think about the actual distance between Apple Pencil and the display. You don’t want people to inadvertently perform an action — especially a destructive action that they might want to undo — just because they hold Apple Pencil near the screen."
},
{
"type": "paragraph",
"text": "Prefer showing a preview value that’s near the middle in a range of dynamic values. Dynamic properties like opacity or flow can be difficult to depict at the highest or lowest ends of the spectrum. For example, previewing the appearance of a brush mark made with the maximum pressure could occlude the area in which people are marking; in contrast, depicting a mark made with the minimum pressure could be hard for people to detect, making the preview an inaccurate representation of an actual mark or even invisible."
},
{
"type": "paragraph",
"text": "Consider using hover to support relevant interactions close to where people are marking. For example, you might respond to hover by displaying a contextual menu of tool sizes when people perform a gesture like squeeze or press a modifier key on an attached keyboard. Revealing a menu near where people are marking lets them make choices without moving Apple Pencil or their hands to another part of the screen."
},
{
"type": "paragraph",
"text": "Prefer showing hover previews for Apple Pencil, not for a pointing device. Although a pointing device can also respond to hover gestures, it might be confusing to provide the same visual feedback for both devices. If it makes sense in your app, you can restrict your hover preview to Apple Pencil only. For developer guidance, see Adopting hover support for Apple Pencil."
}
]
},
{
"heading": "Double tap",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Respect people’s settings for the double-tap gesture when they make sense in your app. By default, models of Apple Pencil that support the double-tap gesture respond by toggling between the current tool and the eraser, but people can set the gesture to toggle between the current and previous tool, show and hide the color picker, or do nothing at all. If your app supports these behaviors, let people use their preferred gestures to perform them. If the systemwide double-tap settings don’t make sense in your app, you can still use the gesture to change the interaction mode. For example, a 3D app that offers a mesh-editing tool could use double tap to toggle between the tool’s raise and lower modes."
},
{
"type": "paragraph",
"text": "Give people a way to specify custom double-tap behavior if necessary. If you offer custom double-tap behavior in addition to some or all of the default behaviors, provide a control that lets people choose the custom behavior mode. People need to know which mode they’re in; otherwise, they may get confused when your app responds differently to their interactions. In this scenario, make sure it’s easy for people to discover the custom behavior your app supports, but don’t turn it on by default."
},
{
"type": "paragraph",
"text": "Avoid using the double-tap gesture to perform an action that modifies content. In rare cases, it’s possible for people to double-tap accidentally, which means that they may not even be aware that your app has performed the action. Prefer using double tap to perform actions that are easy for people to undo. In particular, avoid using double tap to perform a potentially destructive action that might result in data loss."
}
]
},
{
"heading": "Squeeze",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Using Apple Pencil Pro, people can squeeze to perform an action. You can design a custom behavior that responds to squeeze, but recognize that people may choose to configure the squeeze gesture to run an App Shortcut instead of app-specific actions."
},
{
"type": "note",
"text": "NoteThe squeeze gesture is available only when the paired iPad screen is on and while the Apple Pencil Pro is not directly contacting it. Because squeeze works when there’s distance between Apple Pencil Pro and iPad, people might not always be visually aware of the gesture’s onscreen result."
},
{
"type": "paragraph",
"text": "Treat squeeze as a single, quick gesture that performs a discrete — not continuous — action. People sometimes squeeze with a lot of force, so holding a squeeze or squeezing several times quickly can be tiring. Help people remain comfortable by responding to a single squeeze and promptly displaying the result."
},
{
"type": "paragraph",
"text": "If you use squeeze to reveal app UI, like a contextual menu, display it close to Apple Pencil Pro. Displaying the result of a squeeze near the tip of Apple Pencil Pro strengthens the connection between the device and the gesture, and can help people stay engaged with their task."
},
{
"type": "paragraph",
"text": "Define squeeze actions that are nondestructive and easy to undo. As with the double-tap gesture, people can make the squeeze gesture without meaning to, so it’s essential to avoid using squeeze to perform an action that could result in data loss."
}
]
},
{
"heading": "Barrel roll",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "While marking with Apple Pencil Pro, people can use a barrel-roll gesture to change the type of mark they’re making. For example, while using Apple Pencil Pro to highlight content in Notes, people can barrel-roll to rotate the angle of the mark."
},
{
"type": "paragraph",
"text": "Use barrel roll only to modify marking behavior, not to enable navigation or display other controls. In contrast to double tap and squeeze, barrel roll is naturally related to marking and doesn’t make sense for performing an interface action."
}
]
},
{
"heading": "Scribble",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "With Scribble and Apple Pencil, people can simply write wherever text is accepted in your app — they don’t have to tap or switch modes first. Because Scribble is fully integrated into iPadOS, it’s available to all apps by default."
},
{
"type": "paragraph",
"text": "Make text entry feel fluid and effortless. By default, Scribble works in all standard text components — such as text fields, text views, search fields, and editable fields in web content — except password fields. If you use a custom text field in your app, avoid making people tap or select it before they can begin writing."
},
{
"type": "paragraph",
"text": "Make Scribble available everywhere people might want to enter text. Unlike using the keyboard, using Apple Pencil encourages people to treat the screen the way they treat a sheet of paper. Help strengthen this perception in your app by making Scribble consistently available in places where text entry seems natural. For example, in Reminders, it’s natural for people to create a new reminder by writing it in the blank space below the last item, even though the area doesn’t contain a text field. For developer guidance, see UIIndirectScribbleInteraction."
},
{
"type": "paragraph",
"text": "Avoid distracting people while they write. Some text field behaviors work well for keyboard input, but can disrupt the natural writing experience that Apple Pencil provides. For example, it’s best to avoid displaying autocompletion text as people write in a text field because the suggestions can visually interfere with their writing. It’s also a good idea to hide a field’s placeholder text the moment people begin to write so that their input doesn’t appear to overlap it."
},
{
"type": "paragraph",
"text": "While people are writing in a text field, make sure it remains stationary. In some cases, it can make sense to move a text field when it becomes focused: for example, a search field might move to make more room to display results. Such a movement is fine when people are using the keyboard, but when they’re writing it can make them feel like they’ve lost control of where their input is going. If you can’t prevent a text field from moving or resizing, consider delaying the change until people pause their writing."
},
{
"type": "paragraph",
"text": "Prevent autoscrolling text while people are writing and editing in a text field. When transcribed text autoscrolls, people might try to avoid writing on top of it. Worse, if text scrolls while people are using Apple Pencil to select it, they might select a different range of text than they want."
},
{
"type": "paragraph",
"text": "Give people enough space to write. A small text field can feel uncomfortable to write in. When you know that Apple Pencil input is likely, improve the writing experience in your app by increasing the size of the text field before people begin to write in it or when they pause writing; avoid resizing a text field while people are writing. For developer guidance, see UIScribbleInteraction."
}
]
},
{
"heading": "Custom drawing",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Using PencilKit, you can let people take notes, annotate documents and images, and draw with the same low-latency experience that iOS provides. PencilKit also makes it easy to create a custom drawing canvas in your app and offer a state-of-the-art tool picker and ink palette."
},
{
"type": "paragraph",
"text": "Help people draw on top of existing content. By default, the colors on your PencilKit canvas dynamically adjust to Dark Mode, so people can create content in either mode and the results will look great in both. However, when people draw on top of existing content like a PDF or a photo, you want to prevent the dynamic adjustment of colors so that the markup remains sharp and visible."
},
{
"type": "paragraph",
"text": "Consider displaying custom undo and redo buttons when your app runs in a compact environment. In a regular environment, the tool picker includes undo and redo buttons, but in a compact environment it doesn’t. In a compact environment, you could display undo and redo buttons in a toolbar. You might also consider supporting the standard 3-finger undo/redo gesture, so people can use it in any environment. For guidance, see Undo and redo."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, macOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Entering data"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "PencilKit"
},
{
"type": "paragraph",
"text": "PaperKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"May 7, 2024",
"Added guidance for handling squeeze and barrel roll on Apple Pencil Pro."
],
[
"September 12, 2023",
"Updated artwork."
],
[
"November 3, 2022",
"Added guidelines for using hover to enhance your app."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Best-practices"
},
{
"title": "barrel roll",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Barrel-roll"
},
{
"title": "Hover",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Hover"
},
{
"title": "squeeze",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Squeeze"
},
{
"title": "Double tap",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Double-tap"
},
{
"title": "App Shortcut",
"url": "/design/human-interface-guidelines/app-shortcuts"
},
{
"title": "Scribble",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Scribble"
},
{
"title": "Custom drawing",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Custom-drawing"
},
{
"title": "Undo and redo",
"url": "/design/human-interface-guidelines/undo-and-redo"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Related"
},
{
"title": "Entering data",
"url": "/design/human-interface-guidelines/entering-data"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble#Change-log"
}
],
"image_count": 0
},
{
"title": "Camera Control",
"url": "https://developer.apple.com/design/human-interface-guidelines/camera-control",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "On iPhone 16 and iPhone 16 Pro models, the Camera Control quickly opens your app’s camera experience to capture moments as they happen. When a person lightly presses the Camera Control, the system displays an overlay that extends from the device bezel."
},
{
"type": "paragraph",
"text": "The overlay allows people to quickly adjust controls. A person can view the available controls by lightly double-pressing the Camera Control. After selecting a control, they can slide their finger on the Camera Control to adjust a value to capture their content as they want."
},
{
"type": "paragraph",
"text": "Controls in the overlay"
}
]
},
{
"heading": "Anatomy",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The Camera Control offers two types of controls for adjusting values or changing between options:"
},
{
"type": "list",
"items": [
"A slider provides a range of values to choose from, such as how much contrast to apply to the content.",
"A picker offers discrete options, such as turning a grid on and off in the viewfinder."
]
},
{
"type": "paragraph",
"text": "Slider control"
},
{
"type": "paragraph",
"text": "Picker control"
},
{
"type": "paragraph",
"text": "In addition to custom controls that you create, the system provides a set of standard controls that you can optionally include in the overlay to allow someone to adjust their camera’s zoom and exposure."
},
{
"type": "paragraph",
"text": "Zoom factor control"
},
{
"type": "paragraph",
"text": "Exposure bias control"
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use SF Symbols to represent control functionality. The system doesn’t support custom symbols; instead, pick a symbol from SF Symbols that clearly denotes a control’s behavior. iOS offers thousands of symbols you can use to represent the controls your app shows in the overlay. Symbols for controls don’t represent their current state. To view available symbols, see the Camera & Photos section in the SF Symbols app."
},
{
"type": "paragraph",
"text": "The bolt.fill symbol that represents a control for the camera flash"
},
{
"type": "paragraph",
"text": "The camera.filters symbol that represents a control for filters"
},
{
"type": "paragraph",
"text": "Keep names of controls short. Control labels adhere to Dynamic Type sizes, and longer names may obfuscate the camera’s viewfinder."
},
{
"type": "paragraph",
"text": "Include units or symbols with slider control values to provide context. Providing descriptive information in the overlay, such as EV, %, or a custom string, helps people understand what the slider controls. For developer guidance, see localizedValueFormat."
},
{
"type": "paragraph",
"text": "Value with context"
},
{
"type": "paragraph",
"text": "Value without context"
},
{
"type": "paragraph",
"text": "Define prominent values for a slider control. Prominent values are ones people choose most frequently, or values that are evenly spaced, like the major increments of zoom factor. When a person slides on the Camera Control to adjust a slider control, the system more easily lands on prominent values you define. For developer guidance, see prominentValues."
},
{
"type": "paragraph",
"text": "Make space for the overlay in the viewfinder. The overlay and control labels occupy the screen area adjacent to the Camera Control in both portrait and landscape orientations. To avoid overlapping the interface elements of your camera capture experience, place your UI outside of the overlay areas. Maximize the height and width of the viewfinder and allow the overlay to appear and disappear over it."
},
{
"type": "paragraph",
"text": "Minimize distractions in the viewfinder. When capturing a photo or video, people appreciate a large preview image with as few visual distractions as possible. Avoid duplicating controls, like sliders and toggles, in your UI and the overlay when the system displays the overlay."
},
{
"type": "paragraph",
"text": "Keep UI minimal."
},
{
"type": "paragraph",
"text": "Avoid showing controls in the viewfinder that people access in the overlay."
},
{
"type": "paragraph",
"text": "Enable or disable controls depending on the camera mode. For example, disable video controls when taking photos. The overlay supports multiple controls, but you can’t remove or add controls at runtime."
},
{
"type": "paragraph",
"text": "Consider how to arrange your controls. Order commonly used controls toward the middle to allow quick access, and include lesser used controls on either side. When a person lightly presses the Camera Control to open the overlay again, the system remembers the last control they used in your app."
},
{
"type": "paragraph",
"text": "Allow people to use the Camera Control to launch your experience from anywhere. Create a locked camera capture extension that lets people configure the Camera Control to launch your app’s camera experience from their locked device, the Home Screen, or from within other apps. For guidance, see Camera experiences on a locked device."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iPadOS, macOS, watchOS, tvOS, or visionOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "SF Symbols"
},
{
"type": "paragraph",
"text": "Controls"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Enhancing your app experience with the Camera Control — AVFoundation"
},
{
"type": "paragraph",
"text": "AVCaptureControl — AVFoundation"
},
{
"type": "paragraph",
"text": "LockedCameraCapture"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"September 9, 2024",
"New page."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Anatomy",
"url": "/design/human-interface-guidelines/camera-control#Anatomy"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/camera-control#Best-practices"
},
{
"title": "Camera experiences on a locked device",
"url": "/design/human-interface-guidelines/controls#Camera-experiences-on-a-locked-device"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/camera-control#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/camera-control#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/camera-control#Related"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "Controls",
"url": "/design/human-interface-guidelines/controls"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/camera-control#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/camera-control#Change-log"
}
],
"image_count": 0
},
{
"title": "Digital Crown",
"url": "https://developer.apple.com/design/human-interface-guidelines/digital-crown",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "On both Apple Vision Pro and Apple Watch, people can use the Digital Crown to interact with the system; on Apple Watch, people can also use the Digital Crown to interact with apps."
},
{
"type": "paragraph",
"text": "The Digital Crown on Apple Vision Pro"
},
{
"type": "paragraph",
"text": "The Digital Crown on Apple Watch"
}
]
},
{
"heading": "Apple Vision Pro",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "On Apple Vision Pro, people use the Digital Crown to:"
},
{
"type": "list",
"items": [
"Adjust volume",
"Adjust the amount of immersion in a portal, an Environment, or an app or game running in a Full Space (for guidance, see Immersive experiences)",
"Recenter content so it’s in front of them",
"Open Accessibility settings",
"Exit an app and return to the Home View"
]
}
]
},
{
"heading": "Apple Watch",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "As people turn the Digital Crown, it generates information you can use to enhance or facilitate interactions with your app, like scrolling or operating standard or custom controls."
},
{
"type": "paragraph",
"text": "Starting with watchOS 10, the Digital Crown takes on an elevated role as the primary input for navigation. On the watch face, people turn the Digital Crown to view widgets in the Smart Stack, and on the Home Screen, people use it to move vertically through their collection of apps. Within apps, people turn the Digital Crown to switch between vertically paginated tabs, and to scroll through list views and variable height pages."
},
{
"type": "paragraph",
"text": "Beyond its use for navigation, turning the Digital Crown generates information you can use to enhance or facilitate interactions with your app, such as inspecting data or operating standard or custom controls."
},
{
"type": "note",
"text": "NoteApps don’t respond to presses on the Digital Crown because watchOS reserves these interactions for system-provided functionality like revealing the Home Screen."
},
{
"type": "paragraph",
"text": "Most Apple Watch models provide haptic feedback for the Digital Crown, which gives people a more tactile experience as they scroll through content. By default, the system provides linear haptic detents — or taps — as people turn the Digital Crown a specific distance. Some system controls, like table views, provide detents as new items scroll onto the screen."
},
{
"type": "paragraph",
"text": "Anchor your app’s navigation to the Digital Crown. Starting with watchOS 10, turning the Digital Crown is the main way people navigate within and between apps. List, tab, and scroll views are vertically oriented, allowing people to use the Digital Crown to easily move between the important elements of your app’s interface. When anchoring interactions to the Digital Crown, also be sure to back them up with corresponding touch screen interactions."
},
{
"type": "paragraph",
"text": "Consider using the Digital Crown to inspect data in contexts where navigation isn’t necessary. In contexts where the Digital Crown doesn’t need to navigate through lists or between pages, it’s a great tool to inspect data in your app. For example, in World Clock, turning the Digital Crown advances the time of day at a selected location, allowing people to compare various times of day to their current time."
},
{
"type": "paragraph",
"text": "Provide visual feedback in response to Digital Crown interactions. For example, pickers change the currently displayed value as people use the Digital Crown. If you track turns directly, use this data to update your interface programmatically. If you don’t provide visual feedback, people are likely to assume that turning the Digital Crown has no effect in your app."
},
{
"type": "paragraph",
"text": "Update your interface to match the speed with which people turn the Digital Crown. People expect turning the Digital Crown to give them precise control over an interface, so it works well to use this speed to determine the speed at which you make changes. Avoid updating content at a rate that makes it difficult for people to select values."
},
{
"type": "paragraph",
"text": "Use the default haptic feedback when it makes sense in your app. If haptic feedback doesn’t feel right in the context of your app — for example, if the default detents don’t match your app’s animation — turn off the detents. You can also adjust the haptic feedback behavior for tables, letting them use linear detents instead of row-based detents. For example, if your table has rows with significantly different heights, linear detents may give people a more consistent experience."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, macOS, or tvOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Feedback"
},
{
"type": "paragraph",
"text": "Action button"
},
{
"type": "paragraph",
"text": "Immersive experiences"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "WKCrownDelegate — WatchKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"December 5, 2023",
"Added artwork for Apple Vision Pro and Apple Watch, and clarified that visionOS apps don’t receive direct information from the Digital Crown."
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
],
[
"June 5, 2023",
"Added guidelines emphasizing the central role of the Digital Crown for navigation."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Apple Vision Pro",
"url": "/design/human-interface-guidelines/digital-crown#Apple-Vision-Pro"
},
{
"title": "Immersive experiences",
"url": "/design/human-interface-guidelines/immersive-experiences"
},
{
"title": "Apple Watch",
"url": "/design/human-interface-guidelines/digital-crown#Apple-Watch"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/digital-crown#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/digital-crown#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/digital-crown#Related"
},
{
"title": "Feedback",
"url": "/design/human-interface-guidelines/feedback"
},
{
"title": "Action button",
"url": "/design/human-interface-guidelines/action-button"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/digital-crown#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/digital-crown#Change-log"
}
],
"image_count": 0
},
{
"title": "Eyes",
"url": "https://developer.apple.com/design/human-interface-guidelines/eyes",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "When people look at an interactive element, visionOS highlights it, providing visual feedback that helps them confirm the item is one they want. The visual feedback, or hover effect, shows people that they can use an indirect gesture like tap to interact with the element."
},
{
"type": "paragraph",
"text": "In some cases, the system can automatically display an expanded view of a component after people look at it. For example, when people look at a tab bar, the entire bar resizes to reveal text labels next to each tab. In this scenario, an individual tab also highlights before the tab bar expansion to let people select it before revealing the labels. Another example is a button that can reveal a tooltip when people look at it."
},
{
"type": "important",
"text": "ImportantTo help preserve people’s privacy, visionOS doesn’t provide direct information about where people are looking before they tap. When you use system-provided components, visionOS automatically tells you when people tap the component. For developer guidance, see Adopting best practices for privacy and user preferences."
},
{
"type": "paragraph",
"text": "visionOS also supports focus effects that help people navigate apps and the system using a connected input device like a keyboard or game controller. Focus effects are unrelated to the hover effect; to learn more, see Focus and selection."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Always give people multiple ways to interact with your app. Design your app to support the accessibility features people use to personalize the ways they interact with their devices. For guidance, see Accessibility."
},
{
"type": "paragraph",
"text": "Design for visual comfort. Help people accomplish their primary task by making sure that the objects they need to use are within their field of view. When your app or game is running in the Shared Space or a Full Space, the system automatically places the first window or volume people open in a convenient location in front of them. While running in a Full Space, your app or game can also request access to information about a person’s head pose to help you place 3D content appropriately. In all cases, you can improve the visual comfort of your experience when you avoid requiring people to make multiple quick eye adjustments, either over a large area or through multiple levels of depth. For guidance, see Depth."
},
{
"type": "paragraph",
"text": "Place content at a comfortable viewing distance. For example, to help people remain comfortable while they read or engage with content over time, aim to place it at least one meter away. In general, you don’t want to place content very close to people unless they’ll view or interact with it for only a little while."
},
{
"type": "paragraph",
"text": "Prefer using standard UI components. System-provided components respond consistently when people look at them. If your custom components use different visual cues to provide visual feedback, it can be difficult for people to learn and remember how these components work."
}
]
},
{
"heading": "Making items easy to see",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Minimize visual distractions. When there’s a lot of visual noise, it can be difficult for people to find the object they’re looking for. Visual movement can be even more distracting: When people sense movement — especially in their peripheral vision — they tend to respond automatically by looking at it, making it hard to keep looking at the object they’re interested in. For example, revealing content near a button people are looking at can cause them to involuntarily look at the new content instead of the button."
},
{
"type": "paragraph",
"text": "Make it easy for people to look at an item by providing enough space around it. Because eyes naturally tend to make small, quick adjustments in direction even while people are looking at one place, crowding UI objects together can make it difficult for people to look at one of them without jumping to another. You can help ensure that there’s enough space between interactive items by using a margin of at least 16 points around the bounds of each item or by placing items so that their centers are always at least 60 points apart. For additional layout guidance, see Layout and Spatial layout."
},
{
"type": "paragraph",
"text": "Avoid using a repeating pattern or texture that fills the field of view. In some cases, people’s eyes can lock onto different elements in a pattern or texture, making the elements appear to have different depths. To avoid this effect, consider using the pattern in a smaller area."
}
]
},
{
"heading": "Encouraging interaction",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Consider using subtle visual cues to encourage people to look at the item they’re most likely to want. For example, it often works well to place the item near the center of the field of view or use techniques like gentle motion, increased contrast, or variations in color or scale to draw people’s attention. In general, prefer cues that are noticeable without being flashy or harsh."
},
{
"type": "paragraph",
"text": "In general, give an interactive item a rounded shape. People’s eyes tend to be drawn toward the corners in a shape, making it difficult to keep looking at the shape’s center. The more rounded an item’s shape, the easier it is for people to use their eyes to target it."
},
{
"type": "paragraph",
"text": "If you create an interactive component that consists of more than one element, be sure to provide an overall containing shape that visionOS can highlight. For example, if an image and a label below it combine to act as one interactive component, you need to define a custom region that encompasses both elements, allowing visionOS to highlight the entire region when people look at either element."
}
]
},
{
"heading": "Custom hover effects",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "When it makes sense in your app or game, you can design a hover effect that animates in a custom way when people look at an element, including system-provided or custom UI elements and RealityKit entities. You can use a custom hover effect to replace or augment a standard effect."
},
{
"type": "paragraph",
"text": "Before you start designing custom hover effects, it’s important to understand how they work. To enable a custom hover effect for an element, you create two states or appearances for it: one that shows the custom hover effect and one that doesn’t. When someone looks at the element in your app or game, the system applies your predefined hover effect in a process that’s outside of your software’s process. This means that you don’t know when the system applies a custom hover effect or what state the element is in at that moment. The out-of-process nature of a custom hover effect also means that it can’t run code that requires knowing when people are looking at the element."
},
{
"type": "paragraph",
"text": "As an example that shows what a custom hover effect can and can’t do, consider a photo-browsing app where a photo’s custom effect displays a different symbol depending on whether people have added the photo to Favorites. The app specifies the appropriate symbol for a photo’s custom hover effect and the system displays the effect if people look at the photo. However, the hover effect can’t perform the favoriting action because the system doesn’t tell the app when someone is looking at the photo."
},
{
"type": "paragraph",
"text": "Prefer using a custom hover effect to emphasize or enhance a special moment in your experience. People are accustomed to the standard hover effects that provide visual feedback or, in the case of tab bars or tooltips, additional information, so a custom hover effect can be especially noticeable. Adding too many custom hover effects — or using them when standard effects are sufficient — can dilute the impact of your design, distract people from their task, and even cause visual discomfort."
},
{
"type": "paragraph",
"text": "Choose the right delay. An element’s custom hover effect can appear instantly, after a short delay, or after a slightly longer delay, depending on how you expect people to interact with the element."
},
{
"type": "list",
"items": [
"No delay (default). A custom hover effect that appears without delay tends to be especially useful when the effect is subtle or invites interaction, like when a knob appears on a slider.",
"Short delay. Consider using a short delay to let people look at an element and quickly interact with it without waiting for the effect to appear; for example, the expansion of tabs in a tab bar works this way.",
"Long delay. If your custom hover effect shows additional information, like when a tooltip appears below a button, a slightly longer delay can work well because most people won’t need to view the additional information every time."
]
},
{
"type": "paragraph",
"text": "Aim to keep one or more of the element’s primary views unchanged in both states of a custom hover effect. When at least one primary view remains constant during a hover effect’s animation, it provides visual stability that can help people follow the element’s transition. If all of an element’s views move or change during a custom hover effect, it can disorient people and make them lose track of what’s happening."
},
{
"type": "paragraph",
"text": "Thoroughly test custom hover effects. Testing is the only way to determine whether a custom hover effect looks good, responds appropriately, and makes your experience feel alive without distracting people. Aim to test your custom hover effects while wearing Apple Vision Pro so you can develop intuition about how to use them to enhance your experience."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, macOS, tvOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Immersive experiences"
},
{
"type": "paragraph",
"text": "Gestures"
},
{
"type": "paragraph",
"text": "Spatial layout"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Adopting best practices for privacy and user preferences — visionOS"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 10, 2024",
"Added guidance for custom hover effects."
],
[
"March 29, 2024",
"Added artwork showing the visionOS hover effect."
],
[
"October 24, 2023",
"Clarified the difference between focus effects and the visionOS hover effect."
],
[
"June 21, 2023",
"New page."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "indirect gesture",
"url": "/design/human-interface-guidelines/gestures#visionOS"
},
{
"title": "Focus and selection",
"url": "/design/human-interface-guidelines/focus-and-selection"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/eyes#Best-practices"
},
{
"title": "Accessibility",
"url": "/design/human-interface-guidelines/accessibility"
},
{
"title": "field of view",
"url": "/design/human-interface-guidelines/spatial-layout#Field-of-view"
},
{
"title": "Depth",
"url": "/design/human-interface-guidelines/spatial-layout#Depth"
},
{
"title": "Making items easy to see",
"url": "/design/human-interface-guidelines/eyes#Making-items-easy-to-see"
},
{
"title": "Layout",
"url": "/design/human-interface-guidelines/layout"
},
{
"title": "Spatial layout",
"url": "/design/human-interface-guidelines/spatial-layout"
},
{
"title": "Encouraging interaction",
"url": "/design/human-interface-guidelines/eyes#Encouraging-interaction"
},
{
"title": "Custom hover effects",
"url": "/design/human-interface-guidelines/eyes#Custom-hover-effects"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/eyes#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/eyes#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/eyes#Related"
},
{
"title": "Immersive experiences",
"url": "/design/human-interface-guidelines/immersive-experiences"
},
{
"title": "Gestures",
"url": "/design/human-interface-guidelines/gestures"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/eyes#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/eyes#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/eyes#Change-log"
}
],
"image_count": 0
},
{
"title": "Focus and selection",
"url": "https://developer.apple.com/design/human-interface-guidelines/focus-and-selection",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Focus supports simplified, component-based navigation. Using inputs like a remote, game controller, or keyboard, people bring focus to the components they want to interact with."
},
{
"type": "paragraph",
"text": "In many cases, focusing an item also selects it. The exception is when automatic selection might cause a distracting context shift, like opening a new view. In tvOS, for example, people use the remote to move focus from item to item as they seek the one they want, but because selecting a focused item opens or activates it, selection requires a separate gesture."
},
{
"type": "paragraph",
"text": "Different platforms communicate focus in different ways. For example, iPadOS and macOS show focus by drawing a ring around an item or highlighting it; tvOS generally uses the parallax effect to give the focused item an appearance of depth and liveliness. The combination of focus effects and interactions is sometimes called a focus system or focus model."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Rely on system-provided focus effects. System-defined focus effects are precisely tuned to complement interactions with Apple devices, providing experiences that feel responsive, fluid, and lifelike. Incorporating system-provided focus behaviors gives your app consistency and predictability, helping people understand it quickly. Consider creating custom focus effects only if it’s absolutely necessary."
},
{
"type": "paragraph",
"text": "Avoid changing focus without people’s interaction. People rely on the focus system to help them know where they are in your app. If you change focus without their interaction, people have to spend time finding the newly focused item, delaying their current task. The exception is when people are moving focus using an input device that lets them make discrete, directional movements — like a keyboard, remote, or game controller — and a previously focused item disappears. In this scenario, there are only a small number of items within one discrete step of the previously focused item, so moving focus to one of these remaining items ensures that the focus indicator is in a location people can easily find. When people aren’t moving focus by using such an input device, you can’t predict the item they’ll target next, so it’s generally best to simply hide the focus indicator when the focused object disappears."
},
{
"type": "paragraph",
"text": "Be consistent with the platform as you help people bring focus to items in your app. For example, in iPadOS and macOS, a full keyboard access mode helps people use the keyboard to reach every control, so you only need to support focus for content elements like list items, text fields, and search fields, and not for controls like buttons, sliders, and toggles. In contrast, tvOS users rely on using directional gestures on a remote or game controller (or pressing the arrow keys on an attached keyboard) to reach every onscreen element, so you need to make sure that people can bring focus to every element in your app."
},
{
"type": "paragraph",
"text": "Indicate focus using visual appearances that are consistent with the platform. For example, consider a window that contains a list of items. In iPadOS and macOS, the system draws focused list items using white text and a background highlight that matches the app’s accent color, drawing unfocused items using the standard text color and a gray background highlight (for developer guidance, see UICollectionView and NSTableView)."
},
{
"type": "paragraph",
"text": "In general, use a focus ring for a text or search field, but use a highlight in a list or collection. Although you can use a focus ring to draw attention to an item that fills a cell, like a photo, it’s usually easier for people to view lists and collections when an entire row is highlighted."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS or watchOS."
}
]
},
{
"heading": "iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "iPadOS 15 and later defines a focus system that supports keyboard interactions for navigating text fields, text views, and sidebars, in addition to various types of collection views and other custom views in your app."
},
{
"type": "paragraph",
"text": "The iPadOS and tvOS focus systems are similar. People perform actions by moving a focus indicator to an item and then selecting it (for guidance, see tvOS). Although the underlying system is the same, the user experiences are a little different. tvOS uses directional focus, which means people can use the same interaction — that is, swiping the Siri Remote or using only the arrow keys on a connected keyboard — to navigate to every onscreen component. In contrast, iPadOS defines focus groups, which represent specific areas within an app, like a sidebar, grid, or list. Using focus groups, iPadOS can support two different keyboard interactions."
},
{
"type": "list",
"items": [
"Pressing the Tab key moves focus among focus groups, letting people navigate to sidebars, grids, and other app areas.",
"Pressing an arrow key supports a directional focus interaction that’s similar to tvOS, but limited to navigation among items in the same focus group. For example, people can use an arrow key to move through the items in a list or a sidebar."
]
},
{
"type": "paragraph",
"text": "Onscreen components can indicate focus by using the halo effect or the highlighted appearance."
},
{
"type": "paragraph",
"text": "The halo focus effect — also known as the focus ring — displays a customizable outline around the component. You can apply the halo effect to custom views and to fully opaque content within a collection or list cell, such as an image."
},
{
"type": "paragraph",
"text": "Customize the halo focus effect when necessary. By default, the system uses an item’s shape to infer the shape of its halo. If the system-provided halo doesn’t give you the appearance you want, you can refine it to match contours like rounded corners or shapes defined by Bézier paths. You can also adjust a halo’s position if another component occludes or clips it. For example, you might need to ensure that a badge appears above the halo or that a parent view doesn’t clip it. For developer guidance, see UIFocusHaloEffect."
},
{
"type": "paragraph",
"text": "The highlighted appearance — in which the component’s text uses the app’s accent color — also indicates focus, but it’s not a focus effect. The highlight appearance occurs automatically when people select a collection view cell on which you’ve set content configurations (for developer guidance, see UICollectionViewCell)."
},
{
"type": "paragraph",
"text": "Ensure that focus moves through your custom views in ways that make sense. As people continue pressing the Tab key, focus moves through focus groups in reading order: leading to trailing, and top to bottom. Although focus moves through system-provided views in ways that people expect, you might need to adjust the order in which the focus system visits your custom views. For example, if you want focus to move down through a vertical stack of custom views before it moves in the trailing direction to the next view, you need to identify the stack container as a single focus group. For developer guidance, see focusGroupIdentifier."
},
{
"type": "paragraph",
"text": "Adjust the priority of an item to reflect its importance within a focus group. When a group receives focus, its primary item automatically receives focus too, making it easy for people to select the item they’re most likely to want. You can make an item primary by increasing its priority. For developer guidance, see UIFocusGroupPriority."
}
]
},
{
"heading": "tvOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In a full-screen experience, let people use gestures to interact with the content, not to move focus. When an item displays in full screen, it doesn’t show focus, so people naturally assume that their gestures will affect the object, and not its focus state."
},
{
"type": "paragraph",
"text": "Avoid displaying a pointer. People expect to navigate a fixed number of items by changing focus, not by trying to drag a tiny pointer around a huge screen. While free-form movement might make sense during gameplay, such as when looking for a hidden object or flying a plane, use the focus model when people navigate menus and other interface elements. If your app requires a pointer, make sure it’s highly visible and feels integrated with your experience."
},
{
"type": "paragraph",
"text": "Design your interface to accommodate components in various focus states. In tvOS, focusable items can have up to five different states, each of which is visually distinct. Because focusing an item often increases its scale, you need to supply assets for the larger, focused size to ensure they always look sharp, and you need to make sure the larger item doesn’t crowd the surrounding interface."
},
{
"type": "table",
"rows": [
[
"State",
"Description"
],
[
"",
"The viewer hasn’t brought focus to the item. Unfocused items appear less prominent than focused items."
],
[
"",
"The viewer brings focus to the item. A focused item visually stands out from the other onscreen content through elevation to the foreground, illumination, and animation."
],
[
"",
"The viewer chooses the focused item. A focused item provides instant visual feedback when people choose it. For example, a button might briefly invert its colors and animate before it transitions to its selected appearance."
],
[
"",
"The viewer has chosen or activated the item in some way. For example, a heart-shaped button that people can use to favorite a photo might appear filled in the selected state and empty in the deselected state."
],
[
"",
"The viewer can’t bring focus to the item or choose it. An unavailable item appears inactive."
]
]
},
{
"type": "paragraph",
"text": "For developer guidance, see Adding user-focusable elements to a tvOS app."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "visionOS supports the same focus system as in iPadOS and tvOS, letting people use a connected input device like a keyboard or game controller to interact with apps and the system."
},
{
"type": "note",
"text": "NoteWhen people look at a virtual object to identify it as the object they want to interact with, the system uses the hover effect, not a focus effect, to provide visual feedback (for guidance, see Eyes). The hover effect isn’t related to the focus system."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Eyes"
},
{
"type": "paragraph",
"text": "Keyboards"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Focus Attributes — TVML"
},
{
"type": "paragraph",
"text": "Focus-based navigation — UIKit"
},
{
"type": "paragraph",
"text": "About focus interactions for Apple TV — UIKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"October 24, 2023",
"Clarified the difference between focus effects and the visionOS hover effect."
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "parallax effect",
"url": "/design/human-interface-guidelines/images#Parallax-effect"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/focus-and-selection#Best-practices"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/focus-and-selection#Platform-considerations"
},
{
"title": "iPadOS",
"url": "/design/human-interface-guidelines/focus-and-selection#iPadOS"
},
{
"title": "tvOS",
"url": "/design/human-interface-guidelines/focus-and-selection#tvOS"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/focus-and-selection#visionOS"
},
{
"title": "Eyes",
"url": "/design/human-interface-guidelines/eyes"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/focus-and-selection#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/focus-and-selection#Related"
},
{
"title": "Keyboards",
"url": "/design/human-interface-guidelines/keyboards"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/focus-and-selection#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/focus-and-selection#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/focus-and-selection#Change-log"
}
],
"image_count": 0
},
{
"title": "Game controls",
"url": "https://developer.apple.com/design/human-interface-guidelines/game-controls",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "On Apple platforms, a game can support input from physical game controllers or default system interactions, like touch, a remote, or a mouse and keyboard. Players might prefer to use physical game controllers, but there are two important reasons to also support a platform’s default interaction methods:"
},
{
"type": "list",
"items": [
"Even though all platforms except watchOS support physical game controllers, not every player might have access to one.",
"Players appreciate games that let them use the platform interaction method they’re most familiar with."
]
},
{
"type": "paragraph",
"text": "To reach the widest audience and provide the best experience for each platform, keep these factors in mind when choosing the input methods to support."
}
]
},
{
"heading": "Touch controls",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "For iOS and iPadOS games, supporting touch interaction means that you can provide virtual controls on top of game content while also letting players interact with game elements by touching them directly. You can use the Touch Controller framework to add these virtual controls to your game. Keep the following guidelines in mind to create an enjoyable touch control experience."
},
{
"type": "paragraph",
"text": "Determine whether it makes sense to display virtual controls on top of game content. In general, virtual game controls benefit games that offer a large number of actions or require players to control movement. However, sometimes gameplay is more immersive and effective when players can interact directly with in-game objects. Look for opportunities to reduce the amount of virtual controls that overlap your game content by associating actions with in-game gestures instead. For example, consider letting players tap objects to select them instead of adding a virtual selection button."
},
{
"type": "paragraph",
"text": "Place virtual buttons where they’re easy to access. Take into account the device’s boundaries and safe areas as well as comfortable locations for controls. Make sure to position buttons where they don’t overlap system features like the Home indicator or Dynamic Island on iPhone. Place frequently used buttons near a player’s thumb, avoiding the circular regions where players expect movement and camera input to happen. Place secondary controls, like menus, at the top of the screen."
},
{
"type": "paragraph",
"text": "Placing virtual controls within reach of people’s thumbs can make your game more comfortable to play."
},
{
"type": "paragraph",
"text": "Make sure controls are large enough. Make sure frequently used controls are a minimum size of 44x44 pt, and less important controls, such as menus, are a minimum size of 28x28 pt to accommodate people’s fingers."
},
{
"type": "paragraph",
"text": "Always include visible and tactile press states. A virtual control feels unresponsive without a visual and physical press state. Help players understand when they successfully interact with a button by adding a visual press state effect, such as a glow, that they can see even when their finger is covering the control. Combine this press state with sound and haptics to enhance the feeling of feedback. For guidance, see Playing haptics."
},
{
"type": "paragraph",
"text": "Use symbols that communicate the actions they perform. Choose artwork that visually represents the action each button performs, such as a graphic of a weapon to represent an attack. Avoid using abstract shapes or controller-based naming like A, X, or R1 as artwork, which makes it harder for players to understand and remember what specific controls do."
},
{
"type": "paragraph",
"text": "Show and hide virtual controls to reflect gameplay. Take advantage of the dynamic nature of touch controls and adapt what controls players see onscreen depending on their context. You can hide controls when an action isn’t available or relevant, letting you reduce clutter and help players concentrate on what’s important. For example, consider hiding movement controls until a player touches the screen to reduce the amount of UI overlapping your game content."
},
{
"type": "paragraph",
"text": "When the thumbstick moves to the right, it becomes more visible and shows a highlight to indicate the movement direction."
},
{
"type": "paragraph",
"text": "When the thumbstick is at rest, the virtual control fades to show it’s not in use."
},
{
"type": "paragraph",
"text": "Combine functionality into a single control. Consider redesigning game mechanics that require players to press multiple buttons at the same time or in a sequence. Leverage gestures such as double tap and touch and hold to provide different variations of the same action, such as touch and hold to use a special powered up version of an attack. For multiple actions, such as walking or sprinting, consider combining the actions into a single control."
},
{
"type": "paragraph",
"text": "Map movement and camera controls to predictable behavior. Typically, players expect to control movement using the left side of their screen, and control camera direction using the right side of their screen. Maximize the amount of space that players can control both movement and the camera direction by using as large of an input area as possible. For movement control, opt to show a virtual thumbstick wherever the player lands their thumb instead of a static thumbstick position. For camera control, opt to use direct touch to pan the camera instead of a virtual thumbstick."
}
]
},
{
"heading": "Physical controllers",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Support the platform’s default interaction method. A game controller is an optional purchase, but every iPhone and iPad has a touchscreen, every Mac has a keyboard and a trackpad or mouse, every Apple TV has a remote, and every Apple Vision Pro responds to gestures people make with their eyes and hands. If you support game controllers, try to make sure there’s a fallback for using the platform’s default interaction method. For developer guidance, see Adding virtual controls to games that support game controllers in iOS."
},
{
"type": "paragraph",
"text": "Tell people about game controller requirements. In tvOS and visionOS, you can require the use of a physical game controller. The App Store displays a “Game Controller Required” badge to help people identify such apps. Remember that people can open your game at any time, even without a connected controller. If your app requires a game controller, check for its presence and gracefully prompt people to connect one. For developer guidance, see GCRequiresControllerUserInteraction."
},
{
"type": "paragraph",
"text": "Automatically detect whether a controller is paired. Instead of having players manually set up a physical game controller, you can automatically detect whether a controller is paired and get its profile. For developer documentation, see Game Controller."
},
{
"type": "paragraph",
"text": "Customize onscreen content to match the connected game controller. To simplify your game’s code, the Game Controller framework assigns standard names to controller elements based on their placement, but the colors and symbols on an actual game controller may differ. Be sure to use the connected controller’s labeling scheme when referring to controls or displaying related content in your interface. For developer guidance, see GCControllerElement."
},
{
"type": "paragraph",
"text": "Map controller buttons to expected UI behavior. Outside of gameplay, players expect to navigate your game’s UI in a way that matches the familiar behavior of the platform they’re playing on. When not controlling gameplay, follow these conventions across all Apple platforms:"
},
{
"type": "table",
"rows": [
[
"Button",
"Expected behavior for UI"
],
[
"A",
"Activates a control"
],
[
"B",
"Cancels an action or returns to previous screen"
],
[
"X",
"—"
],
[
"Y",
"—"
],
[
"Left shoulder",
"Navigates left to a different screen or section"
],
[
"Right shoulder",
"Navigates right to a different screen or section"
],
[
"Left trigger",
"—"
],
[
"Right trigger",
"—"
],
[
"Left/right thumbstick",
"Moves selection"
],
[
"Directional pad",
"Moves selection"
],
[
"Home/logo",
"Reserved for system controls"
],
[
"Menu",
"Opens game settings or pauses gameplay"
]
]
},
{
"type": "paragraph",
"text": "Support multiple connected controllers. If there are multiple controllers connected, use labels and glyphs that match the one that the player is actively using. If your game supports multiplayer, use the appropriate labels and symbols when referring to a specific player’s controller. If you need to refer to buttons on multiple controllers, consider listing them together."
},
{
"type": "paragraph",
"text": "Prefer using symbols, not text, to refer to game controller elements. The Game Controller framework makes SF Symbols available for most elements, including the buttons on various brands of game controllers. Using symbols instead of text descriptions can be especially helpful for players who aren’t experienced with controllers because it doesn’t require them to hunt for a specific button label during gameplay."
}
]
},
{
"heading": "Keyboards",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Keyboard players appreciate using keyboard bindings to speed up their interactions with apps and games."
},
{
"type": "paragraph",
"text": "Prioritize single-key commands. Single-key commands are generally easier and faster for players to perform, especially while they’re simultaneously using a mouse or trackpad. For example, you might use the first letter of a menu item as a shortcut, such as I for Inventory or M for Map; you might also map the game’s main action to the Space bar, taking advantage of the key’s relatively large size."
},
{
"type": "paragraph",
"text": "Test key binding comfort game using an Apple keyboard. For example, if a key binding uses the Control key (^) on a non-Apple keyboard, consider remapping it to the Command key (⌘) on an Apple keyboard. On Apple keyboards, the Command key is conveniently located next to the Space bar, making it especially easy to reach when players are using the W, A, S, and D keys."
},
{
"type": "paragraph",
"text": "Take the proximity of keys into account. For example, if players navigate using the W, A, S, and D keys, consider using nearby keys to define other high-value commands. Similarly, if there’s a group of closely related actions, it can work well to map their bindings to keys that are physically close together, such as using the number keys for inventory categories."
},
{
"type": "paragraph",
"text": "Let players customize key bindings. Although players tend to expect a reasonable set of defaults, many people need to customize a game’s key bindings for personal comfort and play style."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "Match spatial game controller behavior to hand input. In addition to supporting a wide array of wireless game controllers, your visionOS game can also support spatial game controllers such as PlayStation VR2 Sense controller. Allow players to interact with your game in a similar manner to how they interact using their hands. Specifically, support looking at an object and pressing the controller’s left or right trigger button to indirectly interact, or reaching out and pressing the left or right trigger button to directly interact. For more information, see visionOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Designing for games"
},
{
"type": "paragraph",
"text": "Gestures"
},
{
"type": "paragraph",
"text": "Keyboards"
},
{
"type": "paragraph",
"text": "Playing haptics"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Create games for Apple platforms"
},
{
"type": "paragraph",
"text": "Touch Controller"
},
{
"type": "paragraph",
"text": "Game Controller"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 9, 2025",
"Updated touch control best practices, updated game controller mapping for UI, and added guidance for spatial game controller support in visionOS."
],
[
"June 10, 2024",
"Added guidance for supporting touch controls and changed title from Game controllers."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Touch controls",
"url": "/design/human-interface-guidelines/game-controls#Touch-controls"
},
{
"title": "safe areas",
"url": "/design/human-interface-guidelines/layout#Guides-and-safe-areas"
},
{
"title": "Playing haptics",
"url": "/design/human-interface-guidelines/playing-haptics"
},
{
"title": "Physical controllers",
"url": "/design/human-interface-guidelines/game-controls#Physical-controllers"
},
{
"title": "SF Symbols",
"url": "/design/human-interface-guidelines/sf-symbols"
},
{
"title": "Keyboards",
"url": "/design/human-interface-guidelines/game-controls#Keyboards"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/game-controls#Platform-considerations"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/game-controls#visionOS"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/gestures#visionOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/game-controls#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/game-controls#Related"
},
{
"title": "Designing for games",
"url": "/design/human-interface-guidelines/designing-for-games"
},
{
"title": "Gestures",
"url": "/design/human-interface-guidelines/gestures"
},
{
"title": "Keyboards",
"url": "/design/human-interface-guidelines/keyboards"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/game-controls#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/game-controls#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/game-controls#Change-log"
}
],
"image_count": 0
},
{
"title": "Gestures",
"url": "https://developer.apple.com/design/human-interface-guidelines/gestures",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Depending on the device they’re using, people can make gestures on a touchscreen, in the air, or on a range of input devices such as a trackpad, mouse, remote, or game controller that includes a touch surface."
},
{
"type": "paragraph",
"text": "Every platform supports basic gestures like tap, swipe, and drag. Although the precise movements that make up basic gestures can vary per platform and input device, people are familiar with the underlying functionality of these gestures and expect to use them everywhere. For a list of these gestures, see Standard gestures."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Give people more than one way to interact with your app. People commonly prefer or need to use other inputs — such as their voice, keyboard, or Switch Control — to interact with their devices. Don’t assume that people can use a specific gesture to perform a given task. For guidance, see Accessibility."
},
{
"type": "paragraph",
"text": "In general, respond to gestures in ways that are consistent with people’s expectations. People expect most gestures to work the same regardless of their current context. For example, people expect tap to activate or select an object. Avoid using a familiar gesture like tap or swipe to perform an action that’s unique to your app; similarly, avoid creating a unique gesture to perform a standard action like activating a button or scrolling a long view."
},
{
"type": "paragraph",
"text": "Handle gestures as responsively as possible. Useful gestures enhance the experience of direct manipulation and provide immediate feedback. As people perform a gesture in your app, provide feedback that helps them predict its results and, if necessary, communicates the extent and type of movement required to complete the action."
},
{
"type": "paragraph",
"text": "Indicate when a gesture isn’t available. If you don’t clearly communicate why a gesture doesn’t work, people might think your app has frozen or they aren’t performing the gesture correctly, leading to frustration. For example, if someone tries to drag a locked object, the UI may not indicate that the object’s position has been locked; or if they try to activate an unavailable button, the button’s unavailable state may not be clearly distinct from its available state."
}
]
},
{
"heading": "Custom gestures",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Add custom gestures only when necessary. Custom gestures work best when you design them for specialized tasks that people perform frequently and that aren’t covered by existing gestures, like in a game or drawing app. If you decide to implement a custom gesture, make sure it’s:"
},
{
"type": "list",
"items": [
"Discoverable",
"Straightforward to perform",
"Distinct from other gestures",
"Not the only way to perform an important action in your app or game"
]
},
{
"type": "paragraph",
"text": "Make custom gestures easy to learn. Offer moments in your app to help people quickly learn and perform custom gestures, and make sure to test your interactions in real use scenarios. If you’re finding it difficult to use simple language and graphics to describe a gesture, it may mean people will find the gesture difficult to learn and perform."
},
{
"type": "paragraph",
"text": "Use shortcut gestures to supplement standard gestures, not replace them. While you may supply a custom gesture to quickly access parts of your app, people also need simple, familiar ways to navigate and perform actions, even if it means an extra tap or two. For example, in an app that supports navigation through a hierarchy of views, people expect to find a Back button in a top toolbar that lets them return to the previous view with a single tap. To help accelerate this action, many apps also offer a shortcut gesture — such as swiping from the side of a window or touchscreen — while continuing to provide the Back button."
},
{
"type": "paragraph",
"text": "Avoid conflicting with gestures that access system UI. Several platforms offer gestures for accessing system behaviors, like edge swiping in watchOS or rolling your hand over to access system overlays in visionOS. It’s important to avoid defining custom gestures that might conflict with these interactions, as people expect these controls to work consistently. In specific circumstances within games or immersive experiences, developers can work around this area by deferring the system gesture. For more information, see the platform considerations for iOS, iPadOS, watchOS, and visionOS."
}
]
},
{
"heading": "iOS, iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In addition to the standard gestures supported in all platforms, iOS and iPadOS support a few other gestures that people expect."
},
{
"type": "table",
"rows": [
[
"Gesture",
"Common action"
],
[
"Three-finger swipe",
"Initiate undo (left swipe); initiate redo (right swipe)."
],
[
"Three-finger pinch",
"Copy selected text (pinch in); paste copied text (pinch out)."
],
[
"Four-finger swipe (iPadOS only)",
"Switch between apps."
],
[
"Shake",
"Initiate undo; initiate redo."
]
]
},
{
"type": "paragraph",
"text": "Consider allowing simultaneous recognition of multiple gestures if it enhances the experience. Although simultaneous gestures are unlikely to be useful in nongame apps, a game might include multiple onscreen controls — such as a joystick and firing buttons — that people can operate at the same time. For guidance on integrating touchscreen input with Apple Pencil input in your iPadOS app, see Apple Pencil and Scribble."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "People primarily interact with macOS using a keyboard and mouse. In addition, they can make standard gestures on a Magic Trackpad, Magic Mouse, or a game controller that includes a touch surface."
}
]
},
{
"heading": "tvOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "People expect to use standard gestures to navigate tvOS apps and games with a compatible remote, Siri Remote, or game controller that includes a touch surface. For guidance, see Remotes."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "visionOS supports two categories of gestures: indirect and direct."
},
{
"type": "paragraph",
"text": "People use an indirect gesture by looking at an object to target it, and then manipulating that object from a distance — indirectly — with their hands. For example, a person can look at a button to focus it and select it by quickly tapping their finger and thumb together. Indirect gestures are comfortable to perform at any distance, and let people quickly change focus between different objects and select items with minimal movement."
},
{
"type": "paragraph",
"text": "People use a direct gesture to physically touch an interactive object. For example, people can directly type on the visionOS keyboard by tapping the virtual keys. Direct gestures work best when they are within reach. Because people may find it tiring to keep their arms raised for extended periods, direct gestures are best for infrequent use. visionOS also supports direct versions of all standard gestures, allowing people the choice to interact directly or indirectly with any standard component."
},
{
"type": "paragraph",
"text": "Here are the standard direct gestures people use in visionOS; see Specifications for a list of standard indirect gestures."
},
{
"type": "table",
"rows": [
[
"Direct gesture",
"Common use"
],
[
"Touch",
"Directly select or activate an object."
],
[
"Touch and hold",
"Open a contextual menu."
],
[
"Touch and drag",
"Move an object to a new location."
],
[
"Double touch",
"Preview an object or file; select a word in an editing context."
],
[
"Swipe",
"Reveal actions and controls; dismiss views; scroll."
],
[
"With two hands, pinch and drag together or apart",
"Zoom in or out."
],
[
"With two hands, pinch and drag in a circular motion",
"Rotate an object."
]
]
},
{
"type": "paragraph",
"text": "Support standard gestures everywhere you can. For example, as soon as someone looks at an object in your app or game, tap is the first gesture they’re likely to make when they want to select or activate it. Even if you also support custom gestures, supporting standard gestures such as tap helps people get comfortable with your app or game quickly."
},
{
"type": "paragraph",
"text": "Offer both indirect and direct interactions when possible. Prefer indirect gestures for UI and common components like buttons. Reserve direct gestures and custom gestures for objects that invite close-up interaction or specific motions in a game or interactive experience."
},
{
"type": "paragraph",
"text": "Avoid requiring specific body movements or positions for input. Not all people can perform specific body movements or position themselves in certain ways at all times, whether due to disability, spatial constraints, or other environmental factors. If your experience requires movement, consider supporting alternative inputs to let people choose the interaction method that works best for them."
}
]
},
{
"heading": "Designing custom gestures in visionOS",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "If you want to offer a specific interaction for your experience that people can’t perform using an existing system gesture, consider designing a custom gesture. To offer this type of interaction, your app needs to be running in a Full Space, and you must request people’s permission to access information about their hands. For developer guidance, see Setting up access to ARKit data."
},
{
"type": "paragraph",
"text": "Prioritize comfort. Continually test ergonomics of all interactions that require custom gestures. A custom interaction that requires people to keep their arms raised for even a little while can be physically tiring, and repeating very similar movements many times in succession can stress people’s muscles and joints."
},
{
"type": "paragraph",
"text": "Carefully consider complex custom gestures that involve multiple fingers or both hands. People may not always have both hands available when using your app or game. If you require a more complex gesture for your experience, consider also offering an alternative that requires less movement."
},
{
"type": "paragraph",
"text": "Avoid custom gestures that require using a specific hand. It can increase someone’s cognitive load if they need to remember which hand to use to trigger a custom gesture. It may also make your experience less welcoming to people with strong hand-dominance or limb differences."
}
]
},
{
"heading": "Working with system overlays in visionOS",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "In visionOS 2 and later, people can look at the palm of one hand and use gestures to quickly access system overlays for Home and Control Center. These interactions are available systemwide, and are reserved solely for accessing system overlays."
},
{
"type": "note",
"text": "NoteThe system overlay is the default method of accessing Control Center in visionOS 2 and later. The visionOS 1 behavior (looking upward) remains available as an accessibility setting."
},
{
"type": "paragraph",
"text": "When designing apps and games that use custom gestures or anchor content to a person’s hands, it’s important to take interactions with the system overlays into consideration."
},
{
"type": "paragraph",
"text": "Reserve the area around a person’s hand for system overlays and their related gestures. If possible, don’t anchor content to a person’s hands or wrists. If you’re designing a game that involves hand-anchored content, place it outside of the immediate area of someone’s hand to avoid colliding with the Home indicator."
},
{
"type": "paragraph",
"text": "The area reserved for interacting with system overlays."
},
{
"type": "paragraph",
"text": "A person looks at their palm to reveal the Home indicator."
},
{
"type": "paragraph",
"text": "A person turns their hand to reveal the status bar, and can tap to open Control Center."
},
{
"type": "paragraph",
"text": "Consider deferring the system overlay behavior when designing an immersive app or game. In certain circumstances, you may not want the Home indicator to appear when someone looks at the palm of their hand. For example, a game that uses virtual hands or gloves may want to keep someone within the world of the story, even if they happen to look at their hands from different angles. In such cases, when your app is running in a Full Space, you can choose to require a tap to reveal the Home indicator instead. For developer guidance, see persistentSystemOverlays(_:)."
},
{
"type": "paragraph",
"text": "Default behavior in the Shared Space"
},
{
"type": "paragraph",
"text": "Default behavior in a Full Space"
},
{
"type": "paragraph",
"text": "Deferred behavior in a Full Space"
},
{
"type": "note",
"text": "NoteApps and games that you built for visionOS 1 defer the system overlay behavior by default. When a person looks at their palm with your app running in a Full Space, the Home indicator won’t appear unless they tap first."
},
{
"type": "paragraph",
"text": "Use caution when designing custom gestures that involve a rolling motion of the hand, wrist, and forearm. This specific motion is reserved for revealing system overlays. Since system overlays always display on top of app content and your app isn’t aware of when they’re visible, it’s important to test any custom gestures or content that might conflict."
}
]
},
{
"heading": "Double tap",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "In watchOS 11 and later, people can use the double-tap gesture to scroll through lists and scroll views, and to advance between vertical tab views. Additionally, you can specify a toggle or button as the primary action in your app, or in your widget or Live Activity when the system displays it in the Smart Stack. Double-tapping in a view with a primary action highlights the control and then performs the action. The system also supports double tap for custom actions that you offer in notifications, where it acts on the first nondestructive action in the notification."
},
{
"type": "paragraph",
"text": "Avoid setting a primary action in views with lists, scroll views, or vertical tabs. This conflicts with the default navigation behaviors that people expect when they double-tap."
},
{
"type": "paragraph",
"text": "Choose the button that people use most commonly as the primary action in a view. Double tap is helpful in a nonscrolling view when it performs the action that people use the most. For example, in a media controls view, you could assign the primary action to the play/pause button. For developer guidance, see handGestureShortcut(_:isEnabled:) and primaryAction."
}
]
},
{
"heading": "Standard gestures",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "The system provides APIs that support the familiar gestures people use with their devices, whether they use a touchscreen, an indirect gesture in visionOS, or an input device like a trackpad, mouse, remote, or game controller. For developer guidance, see Gestures."
},
{
"type": "table",
"rows": [
[
"Gesture",
"Supported in",
"Common action"
],
[
"Tap",
"iOS, iPadOS, macOS, tvOS, visionOS, watchOS",
"Activate a control; select an item."
],
[
"Swipe",
"iOS, iPadOS, macOS, tvOS, visionOS, watchOS",
"Reveal actions and controls; dismiss views; scroll."
],
[
"Drag",
"iOS, iPadOS, macOS, tvOS, visionOS, watchOS",
"Move a UI element."
],
[
"Touch (or pinch) and hold",
"iOS, iPadOS, tvOS, visionOS, watchOS",
"Reveal additional controls or functionality."
],
[
"Double tap",
"iOS, iPadOS, macOS, tvOS, visionOS, watchOS",
"Zoom in; zoom out if already zoomed in; perform a primary action on Apple Watch Series 9 and Apple Watch Ultra 2."
],
[
"Zoom",
"iOS, iPadOS, macOS, tvOS, visionOS",
"Zoom a view; magnify content."
],
[
"Rotate",
"iOS, iPadOS, macOS, tvOS, visionOS",
"Rotate a selected item."
]
]
},
{
"type": "paragraph",
"text": "For guidance on supporting additional gestures and button presses on specific input devices, see Pointing devices, Remotes, and Game controls."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Feedback"
},
{
"type": "paragraph",
"text": "Eyes"
},
{
"type": "paragraph",
"text": "Playing haptics"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Gestures — SwiftUI"
},
{
"type": "paragraph",
"text": "UITouch — UIKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"September 9, 2024",
"Added guidance for working with system overlays in visionOS and made organizational updates."
],
[
"September 15, 2023",
"Updated specifications to include double tap in watchOS."
],
[
"June 21, 2023",
"Changed page title from Touchscreen gestures and updated to include guidance for visionOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Standard gestures",
"url": "/design/human-interface-guidelines/gestures#Standard-gestures"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/gestures#Best-practices"
},
{
"title": "Accessibility",
"url": "/design/human-interface-guidelines/accessibility"
},
{
"title": "Custom gestures",
"url": "/design/human-interface-guidelines/gestures#Custom-gestures"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/gestures#Platform-considerations"
},
{
"title": "iOS, iPadOS",
"url": "/design/human-interface-guidelines/gestures#iOS-iPadOS"
},
{
"title": "Apple Pencil and Scribble",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/gestures#macOS"
},
{
"title": "keyboard",
"url": "/design/human-interface-guidelines/keyboards"
},
{
"title": "game controller",
"url": "/design/human-interface-guidelines/game-controls"
},
{
"title": "tvOS",
"url": "/design/human-interface-guidelines/gestures#tvOS"
},
{
"title": "Remotes",
"url": "/design/human-interface-guidelines/remotes"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/gestures#visionOS"
},
{
"title": "Specifications",
"url": "/design/human-interface-guidelines/gestures#Specifications"
},
{
"title": "Designing custom gestures in visionOS",
"url": "/design/human-interface-guidelines/gestures#Designing-custom-gestures-in-visionOS"
},
{
"title": "Working with system overlays in visionOS",
"url": "/design/human-interface-guidelines/gestures#Working-with-system-overlays-in-visionOS"
},
{
"title": "watchOS",
"url": "/design/human-interface-guidelines/gestures#watchOS"
},
{
"title": "Double tap",
"url": "/design/human-interface-guidelines/gestures#Double-tap"
},
{
"title": "notifications",
"url": "/design/human-interface-guidelines/notifications"
},
{
"title": "Pointing devices",
"url": "/design/human-interface-guidelines/pointing-devices"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/gestures#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/gestures#Related"
},
{
"title": "Feedback",
"url": "/design/human-interface-guidelines/feedback"
},
{
"title": "Eyes",
"url": "/design/human-interface-guidelines/eyes"
},
{
"title": "Playing haptics",
"url": "/design/human-interface-guidelines/playing-haptics"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/gestures#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/gestures#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/gestures#Change-log"
}
],
"image_count": 0
},
{
"title": "Gyroscope and accelerometer",
"url": "https://developer.apple.com/design/human-interface-guidelines/gyro-and-accelerometer",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "You can use accelerometer and gyroscope data to provide experiences based on real-time, motion-based information in apps and games that run in iOS, iPadOS, and watchOS. tvOS apps can use gyroscope data from the Siri Remote. For developer guidance, see Core Motion."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Use motion data only to offer a tangible benefit to people. For example, a fitness app might use the data to provide feedback about people’s activity and general health, and a game might use the data to enhance gameplay. Avoid gathering data simply to have the data."
},
{
"type": "important",
"text": "ImportantIf your experience needs to access motion data from a device, you must provide copy that explains why. The first time your app or game tries to access this type of data, the system includes your copy in a permission request, where people can grant or deny access."
},
{
"type": "paragraph",
"text": "Outside of active gameplay, avoid using accelerometers or gyroscopes for the direct manipulation of your interface. Some motion-based gestures may be difficult to replicate precisely, may be physically challenging for some people to perform, and may affect battery usage."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS, iPadOS, macOS, tvOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Feedback"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Getting processed device-motion data — Core Motion"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer#Best-practices"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer#Related"
},
{
"title": "Feedback",
"url": "/design/human-interface-guidelines/feedback"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer#Videos"
}
],
"image_count": 0
},
{
"title": "Inputs",
"url": "https://developer.apple.com/design/human-interface-guidelines/inputs",
"category": "inputs",
"summary": "",
"sections": [],
"platforms": [],
"related": [
{
"title": "Action button",
"url": "/design/human-interface-guidelines/action-button"
},
{
"title": "Apple Pencil and Scribble",
"url": "/design/human-interface-guidelines/apple-pencil-and-scribble"
},
{
"title": "Camera Control",
"url": "/design/human-interface-guidelines/camera-control"
},
{
"title": "Digital Crown",
"url": "/design/human-interface-guidelines/digital-crown"
},
{
"title": "Eyes",
"url": "/design/human-interface-guidelines/eyes"
},
{
"title": "Focus and selection",
"url": "/design/human-interface-guidelines/focus-and-selection"
},
{
"title": "Game controls",
"url": "/design/human-interface-guidelines/game-controls"
},
{
"title": "Gestures",
"url": "/design/human-interface-guidelines/gestures"
},
{
"title": "Gyroscope and accelerometer",
"url": "/design/human-interface-guidelines/gyro-and-accelerometer"
},
{
"title": "Keyboards",
"url": "/design/human-interface-guidelines/keyboards"
},
{
"title": "Nearby interactions",
"url": "/design/human-interface-guidelines/nearby-interactions"
},
{
"title": "Pointing devices",
"url": "/design/human-interface-guidelines/pointing-devices"
},
{
"title": "Remotes",
"url": "/design/human-interface-guidelines/remotes"
}
],
"image_count": 0
},
{
"title": "Keyboards",
"url": "https://developer.apple.com/design/human-interface-guidelines/keyboards",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "People can connect a physical keyboard to any device except Apple Watch. Mac users tend to use a physical keyboard all the time and iPad users often do. Many games work well with a physical keyboard, and people can prefer using one instead of a virtual keyboard when entering a lot of text."
},
{
"type": "paragraph",
"text": "Keyboard users often appreciate using keyboard shortcuts to speed up their interactions with apps and games. A keyboard shortcut is a combination of a primary key and one or more modifier keys (Control, Option, Shift, and Command) that map to a specific command. A keyboard shortcut in a game — called a key binding — often consists of a single key."
},
{
"type": "paragraph",
"text": "Apple defines standard keyboard shortcuts to work consistently across the system and most apps, helping people transfer their knowledge to new experiences. Some apps define custom keyboard shortcuts for the app-specific commands people use most; most games define custom key bindings that make it quick and efficient to use the keyboard to control the game. For guidance, see Game controls."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Support Full Keyboard Access when possible. Available in iOS, iPadOS, macOS, and visionOS, Full Keyboard Access lets people navigate and activate windows, menus, controls, and system features using only the keyboard. To test Full Keyboard Access in your app or game, turn it on in the Accessibility area of the system-supplied Settings app. For developer guidance, see Support Full Keyboard Access in your iOS app and isFullKeyboardAccessEnabled."
},
{
"type": "important",
"text": "ImportantAlthough iPadOS supports keyboard navigation in text fields, text views, and sidebars, and provides APIs you can use to support it in collection views and other custom views, avoid supporting keyboard navigation for controls, such as buttons, segmented controls, and switches. Instead, let people use Full Keyboard Access to activate controls, navigate to all onscreen components, and perform gesture-based interactions like drag and drop. For guidance, see iPadOS; for developer guidance, see Focus-based navigation."
},
{
"type": "paragraph",
"text": "Respect standard keyboard shortcuts. While using most apps, people generally expect to rely on the standard keyboard shortcuts that work in other apps and throughout the system. If your app offers a unique action that people perform frequently, prefer creating a custom shortcut for it instead of repurposing a standard one that people associate with a different action. While playing a game, people may expect to use certain standard keyboard shortcuts — such as Command–Q to quit the game — but they also expect to be able to modify each game’s key bindings to fit their personal play style. For guidance, see Game controls."
}
]
},
{
"heading": "Standard keyboard shortcuts",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "In general, don’t repurpose standard keyboard shortcuts for custom actions. People can get confused when the shortcuts they know work differently in your app or game. Only consider redefining a standard shortcut if its action doesn’t make sense in your experience. For example, if your app doesn’t support text editing, it doesn’t need a text-styling command like Italic, so you might repurpose Command–I for an action that has more relevance, like Get Info."
},
{
"type": "paragraph",
"text": "People expect each of the following standard keyboard shortcuts to perform the action listed in the table below."
},
{
"type": "table",
"rows": [
[
"Primary key",
"Keyboard shortcut",
"Action"
],
[
"Space",
"Command-Space",
"Show or hide the Spotlight search field."
],
[
"",
"Shift-Command-Space",
"Varies."
],
[
"",
"Option-Command-Space",
"Show the Spotlight search results window."
],
[
"",
"Control-Command-Space",
"Show the Special Characters window."
],
[
"Tab",
"Shift-Tab",
"Navigate through controls in a reverse direction."
],
[
"",
"Command-Tab",
"Move forward to the next most recently used app in a list of open apps."
],
[
"",
"Shift-Command-Tab",
"Move backward through a list of open apps (sorted by recent use)."
],
[
"",
"Control-Tab",
"Move focus to the next group of controls in a dialog or the next table (when Tab moves to the next cell)."
],
[
"",
"Control-Shift-Tab",
"Move focus to the previous group of controls."
],
[
"Esc",
"Esc",
"Cancel the current action or process."
],
[
"Esc",
"Option-Command-Esc",
"Open the Force Quit dialog."
],
[
"Eject",
"Control-Command-Eject",
"Quit all apps (after changes have been saved to open documents) and restart the computer."
],
[
"",
"Control-Option-Command-Eject",
"Quit all apps (after changes have been saved to open documents) and shut the computer down."
],
[
"F1",
"Control-F1",
"Toggle full keyboard access on or off."
],
[
"F2",
"Control-F2",
"Move focus to the menu bar."
],
[
"F3",
"Control- F3",
"Move focus to the Dock."
],
[
"F4",
"Control-F4",
"Move focus to the active (or next) window."
],
[
"",
"Control-Shift-F4",
"Move focus to the previously active window."
],
[
"F5",
"Control-F5",
"Move focus to the toolbar."
],
[
"",
"Command-F5",
"Turn VoiceOver on or off."
],
[
"F6",
"Control-F6",
"Move focus to the first (or next) panel."
],
[
"",
"Control-Shift-F6",
"Move focus to the previous panel."
],
[
"F7",
"Control-F7",
"Temporarily override the current keyboard access mode in windows and dialogs."
],
[
"F8",
"",
"Varies."
],
[
"F9",
"",
"Varies."
],
[
"F10",
"",
"Varies."
],
[
"F11",
"",
"Show desktop."
],
[
"F12",
"",
"Hide or display Dashboard."
],
[
"Grave accent (`)",
"Command-Grave accent",
"Activate the next open window in the frontmost app."
],
[
"",
"Shift-Command-Grave accent",
"Activate the previous open window in the frontmost app."
],
[
"",
"Option-Command-Grave accent",
"Move focus to the window drawer."
],
[
"Hyphen (-)",
"Command-Hyphen",
"Decrease the size of the selection."
],
[
"",
"Option-Command-Hyphen",
"Zoom out when screen zooming is on."
],
[
"Left bracket ({)",
"Command-Left bracket",
"Left-align a selection."
],
[
"Right bracket (})",
"Command-Right bracket",
"Right-align a selection."
],
[
"Pipe (|)",
"Command-Pipe",
"Center-align a selection."
],
[
"Colon (:)",
"Command-Colon",
"Display the Spelling window."
],
[
"Semicolon (;)",
"Command-Semicolon",
"Find misspelled words in the document."
],
[
"Comma (,)",
"Command-Comma",
"Open the app’s settings window."
],
[
"",
"Control-Option-Command-Comma",
"Decrease screen contrast."
],
[
"Period (.)",
"Command-Period",
"Cancel an operation."
],
[
"",
"Control-Option-Command-Period",
"Increase screen contrast."
],
[
"Question mark (?)",
"Command-Question mark",
"Open the app’s Help menu."
],
[
"Forward slash (/)",
"Option-Command-Forward slash",
"Turn font smoothing on or off."
],
[
"Equal sign (=)",
"Shift-Command-Equal sign",
"Increase the size of the selection."
],
[
"",
"Option-Command-Equal sign",
"Zoom in when screen zooming is on."
],
[
"3",
"Shift-Command-3",
"Capture the screen to a file."
],
[
"",
"Control-Shift-Command-3",
"Capture the screen to the Clipboard."
],
[
"4",
"Shift-Command-4",
"Capture a selection to a file."
],
[
"",
"Control-Shift-Command-4",
"Capture a selection to the Clipboard."
],
[
"8",
"Option-Command-8",
"Turn screen zooming on or off."
],
[
"",
"Control-Option-Command-8",
"Invert the screen colors."
],
[
"A",
"Command-A",
"Select every item in a document or window, or all characters in a text field."
],
[
"",
"Shift-Command-A",
"Deselect all selections or characters."
],
[
"B",
"Command-B",
"Boldface the selected text or toggle boldfaced text on and off."
],
[
"C",
"Command-C",
"Copy the selection to the Clipboard."
],
[
"",
"Shift-Command-C",
"Display the Colors window."
],
[
"",
"Option-Command-C",
"Copy the style of the selected text."
],
[
"",
"Control-Command-C",
"Copy the formatting settings of the selection and store on the Clipboard."
],
[
"D",
"Option-Command-D",
"Show or hide the Dock."
],
[
"",
"Control-Command-D",
"Display the definition of the selected word in the Dictionary app."
],
[
"E",
"Command-E",
"Use the selection for a find operation."
],
[
"F",
"Command-F",
"Open a Find window."
],
[
"",
"Option-Command-F",
"Jump to the search field control."
],
[
"",
"Control-Command-F",
"Enter full screen."
],
[
"G",
"Command-G",
"Find the next occurrence of the selection."
],
[
"",
"Shift-Command-G",
"Find the previous occurrence of the selection."
],
[
"H",
"Command-H",
"Hide the windows of the currently running app."
],
[
"",
"Option-Command-H",
"Hide the windows of all other running apps."
],
[
"I",
"Command-I",
"Italicize the selected text or toggle italic text on or off."
],
[
"",
"Command-I",
"Display an Info window."
],
[
"",
"Option-Command-I",
"Display an inspector window."
],
[
"J",
"Command-J",
"Scroll to a selection."
],
[
"M",
"Command-M",
"Minimize the active window to the Dock."
],
[
"",
"Option-Command-M",
"Minimize all windows of the active app to the Dock."
],
[
"N",
"Command-N",
"Open a new document."
],
[
"O",
"Command-O",
"Display a dialog for choosing a document to open."
],
[
"P",
"Command-P",
"Display the Print dialog."
],
[
"",
"Shift-Command-P",
"Display the Page Setup dialog."
],
[
"Q",
"Command-Q",
"Quit the app."
],
[
"",
"Shift-Command-Q",
"Log out the person currently logged in."
],
[
"",
"Option-Shift-Command-Q",
"Log out the person currently logged in without confirmation."
],
[
"S",
"Command-S",
"Save a new document or save a version of a document."
],
[
"",
"Shift-Command-S",
"Duplicate the active document or initiate a Save As."
],
[
"T",
"Command-T",
"Display the Fonts window."
],
[
"",
"Option-Command-T",
"Show or hide a toolbar."
],
[
"U",
"Command-U",
"Underline the selected text or turn underlining on or off."
],
[
"V",
"Command-V",
"Paste the Clipboard contents at the insertion point."
],
[
"",
"Shift-Command-V",
"Paste as (Paste as Quotation, for example)."
],
[
"",
"Option-Command-V",
"Apply the style of one object to the selection."
],
[
"",
"Option-Shift-Command-V",
"Paste the Clipboard contents at the insertion point and apply the style of the surrounding text to the inserted object."
],
[
"",
"Control-Command-V",
"Apply formatting settings to the selection."
],
[
"W",
"Command-W",
"Close the active window."
],
[
"",
"Shift-Command-W",
"Close a file and its associated windows."
],
[
"",
"Option-Command-W",
"Close all windows in the app."
],
[
"X",
"Command-X",
"Remove the selection and store on the Clipboard."
],
[
"Z",
"Command-Z",
"Undo the previous operation."
],
[
"",
"Shift-Command-Z",
"Redo (when Undo and Redo are separate commands rather than toggled using Command-Z)."
],
[
"Right arrow",
"Command-Right arrow",
"Change the keyboard layout to current layout of Roman script."
],
[
"",
"Shift-Command-Right arrow",
"Extend selection to the next semantic unit, typically the end of the current line."
],
[
"",
"Shift-Right arrow",
"Extend selection one character to the right."
],
[
"",
"Option-Shift-Right arrow",
"Extend selection to the end of the current word, then to the end of the next word."
],
[
"",
"Control-Right arrow",
"Move focus to another value or cell within a view, such as a table."
],
[
"Left arrow",
"Command-Left arrow",
"Change the keyboard layout to current layout of system script."
],
[
"",
"Shift-Command-Left arrow",
"Extend selection to the previous semantic unit, typically the beginning of the current line."
],
[
"",
"Shift-Left arrow",
"Extend selection one character to the left."
],
[
"",
"Option-Shift-Left arrow",
"Extend selection to the beginning of the current word, then to the beginning of the previous word."
],
[
"",
"Control-Left arrow",
"Move focus to another value or cell within a view, such as a table."
],
[
"Up arrow",
"Shift-Command-Up arrow",
"Extend selection upward in the next semantic unit, typically the beginning of the document."
],
[
"",
"Shift-Up arrow",
"Extend selection to the line above, to the nearest character boundary at the same horizontal location."
],
[
"",
"Option-Shift-Up arrow",
"Extend selection to the beginning of the current paragraph, then to the beginning of the next paragraph."
],
[
"",
"Control-Up arrow",
"Move focus to another value or cell within a view, such as a table."
],
[
"Down arrow",
"Shift-Command-Down arrow",
"Extend selection downward in the next semantic unit, typically the end of the document."
],
[
"",
"Shift-Down arrow",
"Extend selection to the line below, to the nearest character boundary at the same horizontal location."
],
[
"",
"Option-Shift-Down arrow",
"Extend selection to the end of the current paragraph, then to the end of the next paragraph (include the paragraph terminator, such as Return, in cut, copy, and paste operations)."
],
[
"",
"Control-Down arrow",
"Move focus to another value or cell within a view, such as a table."
]
]
},
{
"type": "paragraph",
"text": "The system also defines several keyboard shortcuts for use with localized versions of the system, localized keyboards, keyboard layouts, and input methods. These shortcuts don’t correspond directly to menu commands."
},
{
"type": "table",
"rows": [
[
"Keyboard shortcut",
"Action"
],
[
"Control-Space",
"Toggle between the current and last input source."
],
[
"Control-Option-Space",
"Switch to the next input source in the list."
],
[
"[Modifier key]-Command-Space",
"Varies."
],
[
"Command-Right arrow",
"Change keyboard layout to current layout of Roman script."
],
[
"Command-Left arrow",
"Change keyboard layout to current layout of system script."
]
]
}
]
},
{
"heading": "Custom keyboard shortcuts",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Define custom keyboard shortcuts for only the most frequently used app-specific commands. People appreciate using keyboard shortcuts for actions they perform frequently, but defining too many new shortcuts can make your app seem difficult to learn."
},
{
"type": "paragraph",
"text": "Use modifier keys in ways that people expect. For example, pressing Command while dragging moves items as a group, and pressing Shift while drag-resizing constrains resizing to the item’s aspect ratio. In addition, holding an arrow key moves the selected item by the smallest app-defined unit of distance until people release the key."
},
{
"type": "paragraph",
"text": "Here are the modifier keys and the symbols that represent them."
},
{
"type": "table",
"rows": [
[
"Modifier key",
"Symbol",
"Recommended usage"
],
[
"Command",
"",
"Prefer the Command key as the main modifier key in a custom keyboard shortcut."
],
[
"Shift",
"",
"Prefer the Shift key as a secondary modifier that complements a related shortcut."
],
[
"Option",
"",
"Use the Option modifier sparingly for less-common commands or power features."
],
[
"Control",
"",
"Avoid using the Control key as a modifier. The system uses Control in many systemwide features and shortcuts, like moving focus or capturing screenshots."
]
]
},
{
"type": "tip",
"text": "TipSome languages require modifier keys to generate certain characters. For example, on a French keyboard, Option-5 generates the “{“ character. It’s usually safe to use the Command key as a modifier, but avoid using an additional modifier with characters that aren’t available on all keyboards. If you must use a modifier other than Command, prefer using it only with the alphabetic characters."
},
{
"type": "paragraph",
"text": "List modifier keys in the correct order. If you use more than one modifier key in a custom shortcut, always list them in this order: Control, Option, Shift, Command."
},
{
"type": "paragraph",
"text": "Avoid adding Shift to a shortcut that uses the upper character of a two-character key. People already understand that they must hold the Shift key to type the upper character of a two-character key, so it’s clearer to simply list the upper character in the shortcut. For example, the keyboard shortcut for Hide Status Bar is Command-Slash, whereas the keyboard shortcut for Help is Command-Question mark, not Shift-Command-Slash."
},
{
"type": "paragraph",
"text": "Let the system localize and mirror your keyboard shortcuts as needed. The system automatically localizes a shortcut’s primary and modifier keys to support the currently connected keyboard; if your app or game switches to a right-to-left layout, the system automatically mirrors the shortcut. For guidance, see Right to left."
},
{
"type": "paragraph",
"text": "Avoid creating a new shortcut by adding a modifier to an existing shortcut for an unrelated command. For example, because people are accustomed to using Command-Z for undoing an action, it would be confusing to use Shift-Command-Z as the shortcut for a command that’s unrelated to undo and redo."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS, iPadOS, macOS, or tvOS. Not supported in watchOS."
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In visionOS, an app’s keyboard shortcuts appear in the shortcut interface that displays when people hold the Command key on a connected keyboard. Similar in organization to an app’s menu bar menus on iPad or Mac, the shortcut interface on Apple Vision Pro displays app commands in familiar system-defined menu categories such as File, Edit, and View. Unlike menu bar menus, the shortcut interface displays all relevant categories in one view, listing within each category only available commands that also have shortcuts."
},
{
"type": "paragraph",
"text": "Write descriptive shortcut titles. Because the shortcut interface displays a flat list of all items in each category, submenu titles aren’t available to provide context for their child items. Make sure each shortcut title is descriptive enough to convey its action without the additional context a submenu title might provide. For developer guidance, see discoverabilityTitle."
},
{
"type": "paragraph",
"text": "Recognize that people see an overlay when they use a physical keyboard with your visionOS app or game. When people connect a physical keyboard while using your visionOS app or game, the system displays a virtual keyboard overlay that provides typing completion and other controls."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Virtual keyboards"
},
{
"type": "paragraph",
"text": "Entering data"
},
{
"type": "paragraph",
"text": "Pointing devices"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "KeyboardShortcut — SwiftUI"
},
{
"type": "paragraph",
"text": "Input events — SwiftUI"
},
{
"type": "paragraph",
"text": "Handling key presses made on a physical keyboard — UIKit"
},
{
"type": "paragraph",
"text": "Mouse, Keyboard, and Trackpad — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 9, 2025",
"Moved game-specific key bindings guidance to the Game controls page."
],
[
"June 10, 2024",
"Added game-specific guidance and made organizational updates."
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "virtual keyboard",
"url": "/design/human-interface-guidelines/virtual-keyboards"
},
{
"title": "Game controls",
"url": "/design/human-interface-guidelines/game-controls#Keyboards"
},
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/keyboards#Best-practices"
},
{
"title": "iPadOS",
"url": "/design/human-interface-guidelines/focus-and-selection#iPadOS"
},
{
"title": "custom",
"url": "/design/human-interface-guidelines/keyboards#Custom-keyboard-shortcuts"
},
{
"title": "Standard keyboard shortcuts",
"url": "/design/human-interface-guidelines/keyboards#Standard-keyboard-shortcuts"
},
{
"title": "Right to left",
"url": "/design/human-interface-guidelines/right-to-left"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/keyboards#Platform-considerations"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/keyboards#visionOS"
},
{
"title": "menu bar menus",
"url": "/design/human-interface-guidelines/the-menu-bar"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/keyboards#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/keyboards#Related"
},
{
"title": "Entering data",
"url": "/design/human-interface-guidelines/entering-data"
},
{
"title": "Pointing devices",
"url": "/design/human-interface-guidelines/pointing-devices"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/keyboards#Developer-documentation"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/keyboards#Change-log"
}
],
"image_count": 0
},
{
"title": "Nearby interactions",
"url": "https://developer.apple.com/design/human-interface-guidelines/nearby-interactions",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "A great nearby interaction feels intuitive and natural to people, because it builds on their innate awareness of the world around them. For example, a person playing music on their iPhone can continue listening on their HomePod mini when they bring the devices close together, simply by transferring the audio output from their iPhone to the HomePod mini."
},
{
"type": "paragraph",
"text": "Nearby interactions are available on devices that support Ultra Wideband technology (to learn more, see Ultra Wideband availability), and rely on the Nearby Interaction framework. Before participating in nearby interaction experiences, people grant permission for their device to interact while they’re using your app. The Nearby Interaction APIs help you preserve people’s privacy by relying on randomly generated device identifiers that last only as long as the interaction session your app initiates."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Consider a task from the perspective of the physical world to find inspiration for a nearby interaction. For example, although people can easily use your app’s UI to transfer a song from their iPhone to their HomePod mini, initiating the transfer by bringing the devices close together makes the task feel rooted in the physical world. Discovering the physical actions that inform the concept of a task can help you create an engaging experience that makes performing it feel easy and natural."
},
{
"type": "paragraph",
"text": "Use distance, direction, and context to inform an interaction. Although your app may get information from a variety of sources, prioritizing nearby, contextually relevant information can help you deliver experiences that feel organic. For example, if people want to share content with a friend in a crowded room, the iOS share sheet can suggest a likely recipient by using on-device knowledge about the person’s most frequent and recent contacts. Combining this knowledge with information from nearby devices that include the U1 chip can let the share sheet improve the experience by suggesting the closest contact the person is facing."
},
{
"type": "paragraph",
"text": "Consider how changes in physical distance can guide a nearby interaction. In the physical world, people generally expect their perception of an object to sharpen as they get closer to it. A nearby interaction can mirror this experience by providing feedback that changes with the proximity of an object. For example, when people use iPhone to find an AirTag, the display transitions from a directional arrow to a pulsing circle as they get closer."
},
{
"type": "paragraph",
"text": "Provide continuous feedback. Continuous feedback reflects the dynamism of the physical world and strengthens the connection between a nearby interaction and the task people are performing. For example, when looking for a lost item in Find My, people get continuous updates that communicate the item’s direction and proximity. Keep people engaged by providing uninterrupted feedback that responds to their movements."
},
{
"type": "paragraph",
"text": "Consider using multiple feedback types to create a holistic experience. Fluidly transitioning among visual, audible, and haptic feedback can help a nearby interaction’s task feel more engaging and real. Using more than one type of feedback also lets you vary the experience to coordinate with both the task and the current context. For example, while people are interacting with the device screen, visual feedback makes sense; while people are interacting with their environment, audible and haptic feedback often work better."
},
{
"type": "paragraph",
"text": "Avoid using a nearby interaction as the only way to perform a task. You can’t assume that everyone can experience a nearby interaction, so it’s essential to provide alternative ways to get things done in your app."
}
]
},
{
"heading": "Device usage",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Encourage people to hold the device in portrait orientation. Holding a device in landscape can decrease the accuracy and availability of information about the distance and relative direction of other devices. If you support only portrait orientation while your nearby interaction feature runs, prefer giving people implicit, visual feedback on how to hold the device for an optimal experience; when possible, avoid explicitly telling people to hold the device in portrait."
},
{
"type": "paragraph",
"text": "Design for the device’s directional field of view. Nearby interaction relies on a hardware sensor with a specific field of view similar to that of the Ultra Wide camera in iPhone 11 and later. If a participating device is outside of this field of view, your app might receive information about its distance, but not its relative direction."
},
{
"type": "paragraph",
"text": "Help people understand how intervening objects can affect the nearby interaction experience in your app. When other people, animals, or sufficiently large objects come between two participating devices, the accuracy or availability of distance and direction information can decrease. Consider adding advice on avoiding this situation to onboarding or tutorial content you present."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iPadOS. Not supported in macOS, tvOS, or visionOS."
}
]
},
{
"heading": "iOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "On iPhone, Nearby Interaction APIs provide a peer device’s distance and direction."
}
]
},
{
"heading": "watchOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "On Apple Watch, Nearby Interaction APIs provide a peer device’s distance. Also, all watchOS apps participating in a nearby interaction experience must be in the foreground."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Feedback"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Nearby Interaction"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 21, 2023",
"Changed page title from Spatial interactions."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/nearby-interactions#Best-practices"
},
{
"title": "Device usage",
"url": "/design/human-interface-guidelines/nearby-interactions#Device-usage"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/nearby-interactions#Platform-considerations"
},
{
"title": "iOS",
"url": "/design/human-interface-guidelines/nearby-interactions#iOS"
},
{
"title": "watchOS",
"url": "/design/human-interface-guidelines/nearby-interactions#watchOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/nearby-interactions#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/nearby-interactions#Related"
},
{
"title": "Feedback",
"url": "/design/human-interface-guidelines/feedback"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/nearby-interactions#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/nearby-interactions#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/nearby-interactions#Change-log"
}
],
"image_count": 0
},
{
"title": "Pointing devices",
"url": "https://developer.apple.com/design/human-interface-guidelines/pointing-devices",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "People appreciate the precision and flexibility that pointing devices offer. On a Mac, people typically expect to combine a pointing device with a keyboard as they navigate apps and the system. On iPad and Apple Vision Pro, a pointing device gives people an additional way to interact with apps and content, without replacing touch, eyes, or gestures."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Be consistent when responding to mouse and trackpad gestures. People expect most gestures to work the same throughout the system, regardless of the app or game they’re using. On a Mac, for example, people rely on the “Swipe between pages” gesture to behave the same way whether they’re browsing individual document pages, webpages, or images."
},
{
"type": "paragraph",
"text": "Avoid redefining systemwide trackpad gestures. Even in a game that uses app-specific gestures in a custom way, people expect systemwide gestures to be available; for example, people expect to make familiar gestures to reveal the Dock or Mission Control in macOS. Remember that Mac users can customize the gestures for performing systemwide actions."
},
{
"type": "paragraph",
"text": "Provide a consistent experience in your app, whether people are using gestures, eyes, a pointing device, or a keyboard. People expect to move fluidly between multiple types of input, and they don’t want to learn different interactions for each mode or for each app they use."
},
{
"type": "paragraph",
"text": "Let people use the pointer to reveal and hide controls that automatically minimize or fade out. In iPadOS, for example, people can reveal the minimized Safari toolbar by holding the pointer over it (the toolbar minimizes again when the pointer moves away). People can also move the pointer to reveal or hide playback controls while they watch a full-screen video."
},
{
"type": "paragraph",
"text": "Provide a consistent experience when people press and hold a modifier key while interacting with objects in your app. For example, if people can duplicate an object by pressing and holding the Option key while they drag that object, ensure the result is the same whether they drag using touch or the pointer."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "No additional considerations for iOS. Not supported in tvOS or watchOS."
}
]
},
{
"heading": "iPadOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "iPadOS builds on the traditional pointer experience, automatically adapting the pointer to the current context and providing rich visual feedback at a level of precision that enhances productivity and simplifies common tasks on a touchscreen device. The iPadOS pointing system gives people an additional way to interact with apps and content — it doesn’t replace touch."
},
{
"type": "paragraph",
"text": "Allow multiple selection in custom views when necessary. In iPadOS 15 and later, people can click and drag the pointer over multiple items to select them. As people use the pointer in this way, it expands into a visible rectangle that selects the items it encompasses. Standard nonlist collection views support this interaction by default; if you want to support multiple selection in custom views, you need to implement it yourself. For developer guidance, see UIBandSelectionInteraction."
},
{
"type": "paragraph",
"text": "Distinguish between pointer and finger input only if it provides value. For example, a scrubber can give people an additional way to target a location in a video when they’re using the pointer. In this scenario, people can drag the playhead using either the pointer or touch, but they can use the pointer to click a precise seek destination."
}
]
},
{
"heading": "Pointer shape and content effects",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "iPadOS integrates the appearance and behavior of both the pointer and the element it moves over, bringing focus to the item the pointer is targeting. You can support the system-provided pointer effects or modify them to suit your experience."
},
{
"type": "paragraph",
"text": "By default, the pointer’s shape is a circle, but it can display a system-defined or custom shape when people move it over specific elements or regions. For example, the pointer automatically uses the familiar I-beam shape when people move it over a text-entry area."
},
{
"type": "paragraph",
"text": "With a content effect, the UI element or region beneath the pointer can also change its appearance when people hold the pointer over it. Depending on the type of content effect, the pointer can retain its current shape or transform into a shape that integrates with the element’s new appearance."
},
{
"type": "paragraph",
"text": "iPadOS defines three content effects that bring focus to different types of interactive elements in your app: highlight, lift, and hover."
},
{
"type": "paragraph",
"text": "The highlight effect transforms the pointer into a translucent, rounded rectangle that acts as a background for a control and includes a gentle parallax. The subtle highlighting and movement bring focus to the control without distracting people from their task. By default, iPadOS applies the highlight effect to bar buttons, tab bars, segmented controls, and edit menus."
},
{
"type": "paragraph",
"text": "The lift effect combines a subtle parallax with the appearance of elevation to make an element seem like it’s floating above the screen. As the pointer fades out beneath the element, iPadOS creates the illusion of lift by scaling the element up while adding a shadow below it and a soft specular highlight on top of it. By default, iPadOS applies the lift effect to app icons and to buttons in Control Center."
},
{
"type": "paragraph",
"text": "Hover is a generic effect that lets you apply custom scale, tint, or shadow values to an element as the pointer moves over it. The hover effect combines your custom values to bring focus to an item, but it doesn’t transform the default pointer shape."
}
]
},
{
"heading": "Pointer accessories",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Pointer accessories are visual indicators that help people understand how they can use the pointer to interact with the current UI element. For example, a pointer approaching a resizable element might display small arrows to indicate that the element allows resizing along a certain axis."
},
{
"type": "paragraph",
"text": "Unlike pointer shapes and content effects, accessories are secondary items that can combine with any pointer to communicate additional information. For developer guidance, see UIPointerAccessory."
},
{
"type": "paragraph",
"text": "Use clear, simple images to create custom accessories. A pointer accessory is small, so it’s essential to create an image that communicates the pointer interaction without using too many details."
},
{
"type": "paragraph",
"text": "Consider using the accessory transition to signal a change in an element’s state or behavior. In addition to animating the appearance and disappearance of pointer accessories, the system also animates the transitions among accessory shapes and positions that can accompany content effects. For example, you could communicate that an add action has become unavailable by transitioning the pointer accessory from the plus symbol to the circle.slash symbol."
}
]
},
{
"heading": "Pointer magnetism",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "iPadOS helps people use the pointer to target an element by making the element appear to attract the pointer. People can experience this magnetic effect when they move the pointer close to an element and when they flick the pointer toward an element."
},
{
"type": "paragraph",
"text": "When people move the pointer close to an element, the system starts transforming the pointer’s shape as soon as it reaches the element’s hit region. Because an element’s hit region typically extends beyond its visible boundaries, the pointer begins to transform before it appears to touch the element itself, creating the illusion that the element is pulling the pointer toward it."
},
{
"type": "paragraph",
"text": "When people flick the pointer toward an element, iPadOS examines the pointer’s trajectory to discover the element that’s the most likely target. When there’s an element in the pointer’s path, the system uses magnetism to pull the pointer toward the element’s center."
},
{
"type": "paragraph",
"text": "By default, iPadOS applies magnetism to elements that use the lift effect (like app icons) and the highlight effect (like bar buttons), but not to elements that use hover. Because an element that supports hover doesn’t transform the default pointer shape, adding magnetism could be jarring and might make people feel that they’ve lost control of the pointer."
},
{
"type": "paragraph",
"text": "The system also applies magnetism to text-entry areas, where it can help people avoid skipping to another line if they make unintended vertical movements while they’re selecting text."
}
]
},
{
"heading": "Standard pointers and effects",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "When possible, support the system-provided content effects. People quickly become accustomed to the content effects they see throughout the system and generally expect their experience to apply to every app they use. To provide a consistent user experience, align your interactions with the design intent of each effect. Specifically:"
},
{
"type": "list",
"items": [
"Use highlight for a small element that has a transparent background.",
"Use lift for a small element that has an opaque background.",
"Use hover for large elements and customize the scale, tint, and shadow attributes as needed (for guidance, see Customizing pointers)."
]
},
{
"type": "paragraph",
"text": "Prefer the system-provided pointer appearances for standard buttons and text-entry areas. You can help people feel more comfortable with your app when the pointer behaves in ways they expect."
},
{
"type": "paragraph",
"text": "Add padding around interactive elements to create comfortable hit regions. You might need to experiment to determine the right size for an element’s hit region. If the hit region is too small, it can make people feel that they have to be extra precise when interacting with the element. On the other hand, when an element’s hit region is too large, people can feel that it takes a lot of effort to pull the pointer away from the element. In general, it works well to add about 12 points of padding around elements that include a bezel; for elements without a bezel, it works well to add about 24 points of padding around the element’s visible edges."
},
{
"type": "paragraph",
"text": "Create contiguous hit regions for custom bar buttons. If there’s space between the hit regions of adjacent buttons in a bar, people may experience a distracting motion when the pointer reverts briefly to its default shape as it moves between buttons."
},
{
"type": "paragraph",
"text": "Specify the corner radius of a nonstandard element that receives the lift effect. With the system-provided lift effect, the pointer transforms to match the element’s shape as it fades out. By default, the pointer uses the system-defined corner radius to transform into a rounded rectangle. If your element is a different shape — if it’s a circle, for example — you need to provide the radius so the pointer can animate seamlessly into the shape of the element. For developer guidance, see UIPointerShape.roundedRect(_:radius:)."
}
]
},
{
"heading": "Customizing pointers",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Prefer system-provided pointer effects for custom elements that behave like standard elements. When a custom element behaves like a standard one, people generally expect to interact with it using familiar pointer interactions. For example, if buttons in a custom toolbar don’t use the standard highlight effect, people might think they’re broken."
},
{
"type": "paragraph",
"text": "Use pointer effects in consistent ways throughout your app. For example, if your app helps people draw, provide a similar pointer experience for every drawing area in your app so that people can apply the knowledge they gain in one area to the others."
},
{
"type": "paragraph",
"text": "Avoid creating gratuitous pointer and content effects. People notice when the appearance of the pointer or the UI element beneath it changes, and they expect the changes to be useful. Creating a purely decorative pointer effect can distract and even irritate people without providing any practical value."
},
{
"type": "paragraph",
"text": "Keep custom pointer shapes simple. Ideally, the pointer’s shape signals the action people can take in the current context without drawing too much attention to itself. If people don’t instantly understand your custom pointer shape, they’re likely to waste time trying to discover what the shape means."
},
{
"type": "paragraph",
"text": "Consider enhancing the pointer experience by displaying custom annotations that provide useful information. For example, you could display X and Y values when people hold the pointer over a graphing area in your app. Keynote uses annotations to display the current width and height of a resizable image."
},
{
"type": "paragraph",
"text": "Avoid displaying instructional text with a pointer. A pointer that displays instructional text can make an app seem complicated and difficult to use. Instead of providing instructions, prioritize clarity and simplicity in your interface, so that people can quickly grasp how to use your app whether they’re using the pointer or touching the screen."
},
{
"type": "paragraph",
"text": "Consider the interplay of shadow, scale, and element spacing when defining custom hover effects. In general, reserve scaling for elements that can increase in size without crowding nearby elements. For example, scaling doesn’t work well for a table row because a row can’t expand without overlapping adjacent rows. For an element that has little space around it, consider using a hover effect that includes tint, but not scale and shadow. Note that it doesn’t work well to use shadow without including scale, because an unscaled element doesn’t appear to get closer to the viewer even when its shadow implies that it’s elevated above the screen."
}
]
},
{
"heading": "macOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "macOS supports a wide range of standard mouse and trackpad interactions that people can customize. For example, when a click or gesture isn’t a primary way to interact with content, people can often turn it on or off based on their current workflow. People can also choose specific regions of a mouse or trackpad to invoke secondary clicks, and select specific finger combinations and movements for certain gestures."
},
{
"type": "table",
"rows": [
[
"Click or gesture",
"Expected behavior",
"Mouse",
"Trackpad"
],
[
"Primary click",
"Select or activate an item, such as a file or button.",
"●",
"●"
],
[
"Secondary click",
"Reveal contextual menus.",
"●",
"●"
],
[
"Scrolling",
"Move content up, down, left, or right within a view.",
"●",
"●"
],
[
"Smart zoom",
"Zoom in or out on content, such as a web page or PDF.",
"●",
"●"
],
[
"Swipe between pages",
"Navigate forward or backward between individually displayed pages.",
"●",
"●"
],
[
"Swipe between full-screen apps",
"Navigate forward or backward between full-screen apps and spaces.",
"●",
"●"
],
[
"Mission Control (double-tap the mouse with two fingers or swipe up on the trackpad with three or four fingers)",
"Activate Mission Control.",
"●",
"●"
],
[
"Lookup and data detectors (force click with one finger or tap with three fingers)",
"Display a lookup window above selected content.",
"",
"●"
],
[
"Tap to click",
"Perform the primary click action using a tap rather than a click.",
"",
"●"
],
[
"Force click",
"Click then press firmly to display a Quick Look window or lookup window above selected content. Apply a variable amount of pressure to affect pressure-sensitive controls, such as variable speed media controls.",
"",
"●"
],
[
"Zoom in or out (pinch with two fingers)",
"Zoom in or out.",
"",
"●"
],
[
"Rotate (move two fingers in a circular motion)",
"Rotate content, such as an image.",
"",
"●"
],
[
"Notification Center (swipe from the edge of the trackpad)",
"Display Notification Center.",
"",
"●"
],
[
"App Exposé (swipe down with three or four fingers)",
"Display the current app’s windows in Exposé.",
"",
"●"
],
[
"Launchpad (pinch with thumb and three fingers)",
"Display the Launchpad.",
"",
"●"
],
[
"Show Desktop (spread with thumb and three fingers)",
"Slide all windows out of the way to reveal the desktop.",
"",
"●"
]
]
}
]
},
{
"heading": "Pointers",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "macOS offers a variety of standard pointer styles, which your app can use to communicate the interactive state of an interface element or the result of a drag operation."
},
{
"type": "table",
"rows": [
[
"Pointer",
"Name",
"Meaning",
"AppKit API"
],
[
"",
"Arrow",
"Standard pointer for selecting and interacting with content and interface elements.",
"arrow"
],
[
"",
"Closed hand",
"Dragging to reposition the display of content within a view—for example, dragging a map around in Maps.",
"closedHand"
],
[
"",
"Contextual menu",
"A contextual menu is available for the content below the pointer. This pointer is generally shown only when the Control key is pressed.",
"contextualMenu"
],
[
"",
"Crosshair",
"Precise rectangular selection is possible, such as when viewing an image in Preview.",
"crosshair"
],
[
"",
"Disappearing item",
"A dragged item will disappear when dropped. If the item references an original item, the original is unaffected. For example, when dragging a mailbox out of the favorites bar in Mail, the original mailbox isn’t removed.",
"disappearingItem"
],
[
"",
"Drag copy",
"Duplicates a dragged—not moved—item when dropped into the destination. Appears when pressing the Option key during a drag operation.",
"dragCopy"
],
[
"",
"Drag link",
"During a drag and drop operation, creates an alias of the selected file when dropped. The alias points to the original file, which remains unmoved. Appears when pressing the Option and Command keys during a drag operation.",
"dragLink"
],
[
"",
"Horizontal I beam",
"Selection and insertion of text is possible in a horizontal layout, such as a TextEdit or Pages document.",
"iBeam"
],
[
"",
"Open hand",
"Dragging to reposition content within a view is possible.",
"openHand"
],
[
"",
"Operation not allowed",
"A dragged item can’t be dropped in the current location.",
"operationNotAllowed"
],
[
"",
"Pointing hand",
"The content beneath the pointer is a URL link to a webpage, document, or other item.",
"pointingHand"
],
[
"",
"Resize down",
"Resize or move a window, view, or element downward.",
"resizeDown"
],
[
"",
"Resize left",
"Resize or move a window, view, or element to the left.",
"resizeLeft"
],
[
"",
"Resize left/right",
"Resize or move a window, view, or element to the left or right.",
"resizeLeftRight"
],
[
"",
"Resize right",
"Resize or move a window, view, or element to the right.",
"resizeRight"
],
[
"",
"Resize up",
"Resize or move a window, view, or element upward.",
"resizeUp"
],
[
"",
"Resize up/down",
"Resize or move a window, view, or element upward or downward.",
"resizeUpDown"
],
[
"",
"Vertical I beam",
"Selection and insertion of text is possible in a vertical layout.",
"iBeamCursorForVerticalLayout"
]
]
}
]
},
{
"heading": "visionOS",
"level": 3,
"content": [
{
"type": "paragraph",
"text": "In visionOS, people can attach an external pointing device or keyboard, and use both devices while they continue to use their eyes and hands. If people look at an element and then move the pointer, the system brings focus to the element under the pointer. Your app doesn’t have to do anything to support this behavior."
},
{
"type": "paragraph",
"text": "When a pointing device is attached, the area people are looking at determines the pointer’s context. For example, when people shift their eyes from one window to another, the pointer’s context seamlessly transitions to the new window."
},
{
"type": "paragraph",
"text": "When people use an attached pointing device that supports gestures, like a trackpad or mouse, the pointer hides while people are gesturing, minimizing visual distraction. In this scenario, the pointer remains hidden until people move it, when it reappears in the location they’re looking at."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Entering data"
},
{
"type": "paragraph",
"text": "Keyboards"
}
]
},
{
"heading": "Developer documentation",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Input events — SwiftUI"
},
{
"type": "paragraph",
"text": "Pointer interactions — UIKit"
},
{
"type": "paragraph",
"text": "Mouse, Keyboard, and Trackpad — AppKit"
}
]
},
{
"heading": "Change log",
"level": 2,
"content": [
{
"type": "table",
"rows": [
[
"Date",
"Changes"
],
[
"June 21, 2023",
"Updated to include guidance for visionOS."
]
]
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/pointing-devices#Best-practices"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/pointing-devices#Platform-considerations"
},
{
"title": "iPadOS",
"url": "/design/human-interface-guidelines/pointing-devices#iPadOS"
},
{
"title": "Pointer shape and content effects",
"url": "/design/human-interface-guidelines/pointing-devices#Pointer-shape-and-content-effects"
},
{
"title": "Pointer accessories",
"url": "/design/human-interface-guidelines/pointing-devices#Pointer-accessories"
},
{
"title": "Pointer magnetism",
"url": "/design/human-interface-guidelines/pointing-devices#Pointer-magnetism"
},
{
"title": "Standard pointers and effects",
"url": "/design/human-interface-guidelines/pointing-devices#Standard-pointers-and-effects"
},
{
"title": "Customizing pointers",
"url": "/design/human-interface-guidelines/pointing-devices#Customizing-pointers"
},
{
"title": "macOS",
"url": "/design/human-interface-guidelines/pointing-devices#macOS"
},
{
"title": "Pointers",
"url": "/design/human-interface-guidelines/pointing-devices#Pointers"
},
{
"title": "visionOS",
"url": "/design/human-interface-guidelines/pointing-devices#visionOS"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/pointing-devices#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/pointing-devices#Related"
},
{
"title": "Entering data",
"url": "/design/human-interface-guidelines/entering-data"
},
{
"title": "Keyboards",
"url": "/design/human-interface-guidelines/keyboards"
},
{
"title": "Developer documentation",
"url": "/design/human-interface-guidelines/pointing-devices#Developer-documentation"
},
{
"title": "Videos",
"url": "/design/human-interface-guidelines/pointing-devices#Videos"
},
{
"title": "Change log",
"url": "/design/human-interface-guidelines/pointing-devices#Change-log"
}
],
"image_count": 0
},
{
"title": "Remotes",
"url": "https://developer.apple.com/design/human-interface-guidelines/remotes",
"category": "inputs",
"summary": "",
"sections": [
{
"heading": "Overview",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "In addition to several specific buttons, the Siri Remote combines a clickpad and touch surface to support familiar gestures like swipe and press that people use to navigate tvOS apps, browse channels and content, play and pause media, and make selections."
}
]
},
{
"heading": "Best practices",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Prefer using standard gestures to perform standard actions. Unless people are actively playing a game, they expect the remote to behave in standard ways in every app they use. Redefining or repurposing standard remote behaviors can cause confusion and add complexity to your experience. For guidance, see Gestures."
},
{
"type": "paragraph",
"text": "Be consistent with the tvOS focus experience. The focus experience forges a strong connection between people and the content they’re viewing. Reinforce this link in your app by ensuring that you combine gestures with the focus experience in ways that are familiar to people, such as always moving focus in the same direction as the gesture."
},
{
"type": "paragraph",
"text": "Provide clear feedback that shows people what happens when they make gestures in your app. For example, lightly resting a thumb on the remote shows people where to swipe down so that they can reveal an info area."
},
{
"type": "paragraph",
"text": "Define new gestures only when it makes sense in your app. Within gameplay, for example, custom gestures can be a fun part of the experience. In most other situations, people expect to use standard gestures and may not appreciate having to discover or remember new ones."
},
{
"type": "paragraph",
"text": "Differentiate between press and tap, and avoid responding to an inadvertent tap. Pressing is an intentional action, and it works well for choosing a button, confirming a selection, and initiating an action during gameplay. Tap gestures are fine for navigation or showing additional information, but keep in mind that people might cause an inadvertent tap when they rest a thumb on the remote, pick it up, move it around, or hand it to someone else, so it often works well to avoid responding to taps during live video playback."
},
{
"type": "paragraph",
"text": "Consider using the position of a tap to aid with navigation or gameplay. The remote can differentiate between up, down, left, and right tap gestures on the touch surface. Respond to positional taps only if it makes sense in the context of your app and if such behavior is intuitive and discoverable."
},
{
"type": "paragraph",
"text": "In almost all cases, open the parent of the current screen when people press the Back button. At the top level of an app or game, the parent is the Apple TV Home Screen; within an app, the parent is defined by the app hierarchy, and isn’t necessarily the previous screen. The exception to this standard behavior is when people are actively playing a game, where it can be easy to accidentally press the Back button repeatedly. To avoid disrupting gameplay in this scenario, respond to the Back button by opening an in-game pause menu that lets people use a different interaction to navigate back to the game’s main menu. When the in-game pause menu is open, respond to a Back-button press by closing the menu and resuming the game. Note that people press and hold the Back button to go to the Home Screen from any location. For guidance, see Buttons."
},
{
"type": "paragraph",
"text": "Respond correctly to the Play/Pause button during media playback. When playing music or video, people expect pressing the Play/Pause button to play, pause, or resume playback."
}
]
},
{
"heading": "Gestures",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "The clickpad’s touch surface detects swipes and presses."
},
{
"type": "paragraph",
"text": "Swipe. Swiping lets people scroll effortlessly through large numbers of items with movement that starts fast and then slows down, based on the strength of the swipe. When people swipe up or down on the edge of the remote, they can speed through items very quickly."
},
{
"type": "paragraph",
"text": "Press. People press to activate a control or select an item. Also, people press before swiping to activate scrubbing mode."
}
]
},
{
"heading": "Buttons",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Ensure that your app or game responds to specific presses in the following ways."
},
{
"type": "table",
"rows": [
[
"Button or area",
"Expected behavior in an app",
"Expected behavior in a game"
],
[
"Touch surface (swipe)",
"Navigates. Changes focus.",
"Performs directional pad behavior."
],
[
"Touch surface (press)",
"Activates a control or an item. Navigates deeper.",
"Performs primary button behavior."
],
[
"Back",
"Returns to previous screen. Exits to Apple TV Home Screen.",
"Pauses/resumes gameplay. Returns to previous screen, exits to main game menu, or exits to Apple TV Home Screen."
],
[
"Play/Pause",
"Activates media playback. Pauses/resumes media playback.",
"Performs secondary button behavior. Skips intro video."
]
]
}
]
},
{
"heading": "Compatible remotes",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Some remotes that are compatible with Apple TV include buttons for browsing live TV or other channel-based content. For example, a remote might include a button people can use to open an electronic program guide (EPG) and other buttons they can use to browse the guide or change channels. For developer guidance, see Providing Channel Navigation; for design guidance, see EPG experience."
},
{
"type": "paragraph",
"text": "If your live-viewing app provides an EPG, respond to a remote’s EPG-browsing buttons in ways people expect. When people press a “guide” or “browse” button, they expect your EPG to open. While they’re viewing your EPG, people expect to navigate through it by pressing a “page up” or “page down” button. Avoid responding to these buttons in other ways while people are browsing the EPG. On the Siri Remote and compatible remotes, people can also tap on the upper or lower area of the Touch surface to browse the EPG. If your app doesn’t support an EPG experience, the system routes these button presses to the default guide app on the viewer’s device."
},
{
"type": "paragraph",
"text": "While your content plays, respond to a compatible remote’s “page up” or “page down” button by changing the channel. People expect these buttons to behave differently when they switch between viewing content and browsing an EPG."
}
]
},
{
"heading": "Platform considerations",
"level": 2,
"content": [
{
"type": "paragraph",
"text": "Not supported in iOS, iPadOS, macOS, visionOS, or watchOS."
}
]
},
{
"heading": "Related",
"level": 4,
"content": [
{
"type": "paragraph",
"text": "Use your Siri Remote or Apple TV Remote with Apple TV"
}
]
}
],
"platforms": [],
"related": [
{
"title": "Best practices",
"url": "/design/human-interface-guidelines/remotes#Best-practices"
},
{
"title": "Gestures",
"url": "/design/human-interface-guidelines/remotes#Gestures"
},
{
"title": "focus experience",
"url": "/design/human-interface-guidelines/focus-and-selection"
},
{
"title": "Buttons",
"url": "/design/human-interface-guidelines/remotes#Buttons"
},
{
"title": "Compatible remotes",
"url": "/design/human-interface-guidelines/remotes#Compatible-remotes"
},
{
"title": "EPG experience",
"url": "/design/human-interface-guidelines/live-viewing-apps#EPG-experience"
},
{
"title": "Platform considerations",
"url": "/design/human-interface-guidelines/remotes#Platform-considerations"
},
{
"title": "Resources",
"url": "/design/human-interface-guidelines/remotes#Resources"
},
{
"title": "Related",
"url": "/design/human-interface-guidelines/remotes#Related"
}
],
"image_count": 0
}
]
}
Reference in New Issue View Git Blame Copy Permalink