Core Haptics

Core Haptics

Compose, play, and verify custom haptic patterns with CoreHaptics. Scope: Swift 6.3, iOS 26+, and supported physical hardware.

Contents

• Choose the Right API
• Implementation Workflow
• Capability and Fallback
• Engine Lifecycle
• Choose a Pattern Representation
• Playback and Modulation
• Testing
• Common Mistakes
• Review Checklist
• References

Choose the Right API

Use the smallest API that expresses the interaction:

Do not introduce CHHapticEngine for a normal button tap. Custom haptics add lifecycle, hardware, interruption, power, and physical-device test responsibilities.

Implementation Workflow

1. Define the interaction intent and a non-haptic fallback.
2. Check CHHapticEngine.capabilitiesForHardware() before creating an engine.
3. Retain one engine for the owning feature or experience; do not create one per tap.
4. Install stoppedHandler and resetHandler before starting the engine.
5. Choose a transient event, continuous event, parameter curve, or AHAP asset.
6. Retain players that require live updates, pause/resume, looping, or seeking.
7. Stop players at the interaction boundary and manage engine idle power.
8. Validate rhythm, intensity, fallback, interruptions, and accessibility on hardware.

Load Core Haptics patterns when writing engine ownership, programmatic events, live modulation, parameter curves, or AHAP playback.

Capability and Fallback

Core Haptics is not universally available. Apple specifically lists devices such as iPad, iPod touch, and Apple Vision Pro among devices without haptic feedback support. Check capability at runtime rather than inferring it from platform or model.

import CoreHaptics

struct HapticCapability {
    let supportsHaptics: Bool
    let supportsAudio: Bool

    static var current: Self {
        let hardware = CHHapticEngine.capabilitiesForHardware()
        return Self(
            supportsHaptics: hardware.supportsHaptics,
            supportsAudio: hardware.supportsAudio
        )
    }
}

Keep the product action successful when haptics are unavailable. Provide visual or audio confirmation only when it is appropriate; never make haptics the sole carrier of state or error information.

Engine Lifecycle

• Set handlers before start().
• Treat stoppedHandler as an external-stop notification. It may run off the main thread and is not called for an explicit stop(completionHandler:).
• Treat resetHandler as invalidation of previously prepared engine resources. Restart the engine and recreate any players or registered audio resources the feature still needs.
• Keep callback state synchronization explicit. Hop to the owning actor before changing UI or actor-isolated state.
• Choose one power policy: stop the engine explicitly when unused, or enable isAutoShutdownEnabled and tolerate automatic idle shutdown/restart behavior.

Do not assume foregrounding alone repairs an interrupted engine. Recovery belongs in the engine handlers and should be idempotent.

Choose a Pattern Representation

Programmatic patterns

Use CHHapticEvent and CHHapticPattern when timing and values derive from live application state or the pattern is small. A transient event is a short impulse; a continuous event has a duration and must be stopped at the interaction boundary.

AHAP files

Use bundled .ahap assets when designers need to tune a reusable sequence without rewriting Swift. AHAP represents events, dynamic parameters, parameter curves, and optional synchronized custom audio. Validate the asset in the app bundle and handle load/play errors rather than silently force-unwrapping its URL.

Static versus live changes

• CHHapticEventParameter defines an event's initial intensity, sharpness, or envelope.
• CHHapticParameterCurve schedules gradual changes as part of a pattern.
• CHHapticDynamicParameter changes a running player immediately.

Do not confuse event parameter identifiers such as .hapticIntensity with dynamic control identifiers such as .hapticIntensityControl.

Playback and Modulation

Use makePlayer(with:) for fixed start/stop playback. Use makeAdvancedPlayer(with:) when the feature needs looping, pause/resume, seeking, completion callbacks, or reusable granular control.

For a gesture-driven continuous haptic:

• start one retained player when the gesture begins;
• send bounded intensity and sharpness dynamic parameters to that same player;
• throttle updates to meaningful changes instead of recreating patterns per frame;
• stop the player when the gesture ends or cancels;
• recreate it after an engine reset.

Intensity and sharpness are perceptual controls, not a guarantee of identical output across hardware. Tune on every supported device family in scope.

Testing

Simulator can compile Core Haptics code but cannot validate the tactile result. Test on supported physical hardware and record:

• capability-off fallback;
• cold start and repeated playback;
• background/foreground and audio interruption recovery;
• continuous gesture cancellation;
• Reduce Motion or product-level haptic preference behavior where applicable;
• audible artifacts when synchronized audio is present;
• battery impact for long-running or frequent patterns.

Compile verification proves API availability only. Product review must assess whether the feedback is distinguishable, proportional, and not fatiguing.

Common Mistakes

• Creating and starting a new engine for every interaction.
• Using Core Haptics when sensoryFeedback already expresses the intent.
• Omitting the capability check or making the action depend on haptic support.
• Installing lifecycle handlers after starting the engine.
• Mutating main-actor state directly from engine callbacks.
• Restarting the engine after reset without rebuilding retained players/resources.
• Recreating a continuous player for every drag update.
• Treating Simulator success as tactile verification.
• Playing frequent, intense feedback without a user/product preference or UX review.

Review Checklist

• Core Haptics is justified over system feedback APIs.
• Runtime capability and a non-haptic fallback are present.
• The engine has a clear owner and is retained across playback.
• Stop and reset handlers are installed before start and are thread-safe.
• Reset recovery recreates invalidated players/resources.
• Event and dynamic parameter identifiers are used in the correct context.
• Continuous players stop on completion and cancellation.
• Engine power behavior is deliberate.
• AHAP and audio resources are bundled and error-checked.
• Physical-device and interruption verification is documented.

References

• Core Haptics patterns — engine owner, transient/continuous playback, live parameters, curves, and AHAP.
• Core Haptics
• Preparing your app to play haptics
• Updating haptic parameters in real time
• Representing patterns in AHAP files