Framework

Core Haptics

Compose and play haptic patterns to customize your iOS app's haptic feedback.

Overview

Core Haptics lets you add customized haptic and audio feedback to your app. Use haptics to engage users physically, with tactile and audio feedback that gets attention and reinforces actions. Some system-provided interface elements—like pickers, switches, and sliders—automatically provide haptic feedback as users interact with them. With Core Haptics, you extend this functionality by composing and combining haptics beyond the default patterns.

Your app can play custom haptic patterns crafted from basic building blocks called haptic events (CHHapticEvent). Events can be transient, like the feedback you get from toggling a switch, or continuous, like the vibration or sound from a ringtone. You can use transient and continuous patterns independently, or build your pattern from precise combinations of the two. For example, the following haptic pattern combines a series of transient haptic events, shown in blue as short impulses, with a single continuous haptic event, shown in orange:

A visual representation of a haptic pattern as a series of filled bars. Short blue bars represent transient events, and the wide orange ramp represents a continuous event of decreasing intensity.

Intensity maps to the haptic's amplitude or strength. Sharpness maps to the persistence or frequency of the haptic pattern.

The Core Haptics engine also supports an event type that allows you to play customized audio content as part of your pattern.

To add haptics to your app, you create an instance of CHHapticEngine, load a pattern, and use the engine to create a player to play that pattern. You create a pattern in one of three ways:

  • Dictionaries. Each entry in the dictionary defines a single characteristic of the haptic, like its intensity, start time, or duration. See Playing a Single-Tap Haptic Pattern to learn more about creating a dictionary inline.

  • Arrays of events and parameters. The CHHapticEvent class represents a haptic event as an object in code. The key-value pairs in a dictionary correspond to the properties and parameters associated with a CHHapticEvent. Haptic event objects are just another representation of the haptics dictionary.

  • AHAP files. This JSON-compliant file format specifies a haptic pattern through key-value pairs, analogous to a dictionary literal, except in a text file. Add this file to your Xcode project bundle.

All forms of pattern creation result in patterns with the exact same kind of content.

Topics

Essentials

Preparing Your App to Play Haptics

Set up your app to play haptics.

Playing a Single-Tap Haptic Pattern

Create and play a transient haptic pattern from a dictionary literal inline.

class CHHapticEngine

An object that manages your app's requests to play haptic patterns.

class CHHapticPattern

An object representing a haptic waveform.

File-Based Haptics

Apple Haptic and Audio Pattern (AHAP) files are a JSON-like representation of synced haptics and audio that you can load and play from disk.

Representing Haptic Patterns in AHAP Files

Understand the Apple Haptic and Audio Pattern (AHAP) file format.

Programmatic Haptics

You can synthesize haptics by configuring parameters like haptic intensity and sharpness. Event parameters define the initial state, while dynamic parameters change the pattern during playback.

Playing Collision-Based Haptic Patterns

Play a custom haptic pattern whose strength depends on an object’s collision speed.

class CHHapticEvent

An object that describes a single haptic or audio event.

class CHHapticEventParameter

A static parameter value that represents a single property of the haptic pattern.

class CHHapticDynamicParameter

A value that you send to a haptic pattern player to alter a property value during playback.

class CHHapticParameterCurve

A curve that you send to a haptic pattern player to alter a property value gradually during playback.

Haptic Errors

struct CHHapticError

A struct representing an error in the haptics process.

enum CHHapticError.Code

Haptic error codes.

let CoreHapticsErrorDomain: String

A string representation of the haptic error domain.

Beta Software

This documentation contains preliminary information about an API or technology in development. This information is subject to change, and software implemented according to this documentation should be tested with final operating system software.

Learn more about using Apple's beta software