Table of Contents

    Book an Appointment

    Why Is Customizing the iOS PDFKit Annotation Menu a Challenge in Enterprise Apps?

    During a recent project for a legal technology SaaS platform, we were tasked with building an advanced document review system. The application required rendering highly complex legal contracts using iOS PDFKit within a modern SwiftUI architecture. A core feature of this platform was custom annotations: when a user tapped an annotation, it was supposed to trigger a proprietary SwiftUI drawer displaying AI-generated summaries and review notes.

    However, we encountered a frustrating situation. Every time a user tapped on a `PDFAnnotation`, the native iOS edit menu (displaying Copy, Highlight, Note, etc.) would automatically pop up on the screen. Not only did this native context menu obscure our custom UI, but it also exposed editing capabilities that violated the strict read-only compliance rules of the application.

    In production applications where data integrity and user experience are paramount, you cannot afford to have native framework behaviors hijacking custom workflows. This challenge inspired this article, as many engineering teams waste days fighting undocumented PDFKit behaviors. By sharing our approach, we hope to help others navigate these native UI quirks seamlessly.

    Where Did the PDFAnnotation Menu Issue Surface in Our SwiftUI Architecture?

    The issue became apparent during our QA cycles for the document viewer module. We had wrapped a standard `PDFView` inside a `UIViewRepresentable` to bridge it into our SwiftUI environment. We programmatically injected custom `PDFAnnotation` objects into the document based on the backend data payload.

    The architectural intent was simple: tap the annotation, read the identifier and pass it back to the SwiftUI state to open the corresponding summary drawer. Unfortunately, the moment the tap occurred, PDFKit’s internal gesture recognizers took priority. The default `UIMenuController` appeared over the document. Because PDFKit heavily abstracts its gesture management and responder chain, standard SwiftUI modifiers like `.allowsHitTesting(false)` or native UI tweaks failed to cascade down to the specific annotation boundaries.

    Why Did Standard iOS Interventions Fail to Hide the PDF Menu?

    When you encounter default menu behaviors in iOS, the standard playbook involves disabling interactions, managing the responder chain or suppressing the menu controller. We attempted all of these standard solutions:

    • Disabling Interaction: Setting `isInteractive = false` on the `PDFAnnotation` disabled the menu, but it also completely swallowed the touch event. Our SwiftUI view never received the notification that the user tapped the annotation, breaking the core feature.
    • Overriding canPerformAction: We subclassed `PDFView` and overrode `canPerformAction(_:withSender:)`, returning `false` for menu actions. Surprisingly, the menu still appeared or it presented an empty visual artifact, because PDFKit manages annotation edit menus through deep internal subviews rather than the parent view’s responder chain.
    • Hiding UIMenuController: We utilized the `PDFViewAnnotationHit` notification and immediately called `UIMenuController.shared.hideMenu()`. This resulted in a terrible visual race condition—the menu would flicker onto the screen for a fraction of a second before disappearing, which is unacceptable for enterprise-grade software.

    What Alternative Approaches Did We Consider to Disable the PDFAnnotation Menu?

    Faced with a stubborn framework, our architecture team paused to evaluate several workaround strategies. When companies hire app developer to create a mobile app, they expect the engineering team to think beyond the immediate symptom and understand the framework’s underlying mechanics.

    Could We Rely on Transparent Overlay Views?

    We considered placing a transparent `UIView` over the entire `PDFView`. We could map the annotation coordinates to this overlay and handle touches there. However, zooming and scrolling the PDF made coordinating the coordinate space between the document and the overlay a mathematical nightmare, leading to performance bottlenecks.

    Could We Swizzle the Internal PDFKit Methods?

    Method swizzling the internal classes responsible for the menu presentation was briefly discussed. However, as an engineering partner, we strictly avoid relying on private APIs or swizzling undocumented framework internals. A future iOS update could easily break this implementation, causing production crashes.

    Could We Intercept the Touch Before PDFKit Processes It?

    This was the winning concept. Rather than letting PDFKit detect the tap and launch the menu, we could inject our own `UITapGestureRecognizer` directly into the `PDFView`. By making our custom gesture recognizer a delegate, we could intercept the touch, determine if it hit an annotation, trigger our custom SwiftUI action and forcefully cancel PDFKit’s default touch handling.

    How Did We Finally Prevent the Edit Menu on PDFAnnotation Tap?

    The final implementation involved subclassing `PDFView` and leveraging the `UIGestureRecognizerDelegate`. By evaluating the exact tap location inside the `gestureRecognizer(_:shouldReceive:)` delegate method, we successfully bypassed the default menu.

    Here is the sanitized, generalized approach we implemented in our `UIViewRepresentable` wrapper:

    import PDFKit
    import SwiftUI
    protocol CustomPDFViewDelegate: AnyObject {
        func didTapAnnotation(_ annotation: PDFAnnotation)
    }
    class CustomPDFView: PDFView, UIGestureRecognizerDelegate {
        weak var actionDelegate: CustomPDFViewDelegate?
        override init(frame: CGRect) {
            super.init(frame: frame)
            setupCustomTapGesture()
        }
        required init?(coder: NSCoder) {
            super.init(coder: coder)
            setupCustomTapGesture()
        }
        private func setupCustomTapGesture() {
            let customTap = UITapGestureRecognizer(target: self, action: #selector(handleCustomTap(_:)))
            customTap.delegate = self
            // Ensure our gesture is recognized alongside the scroll view's gestures
            self.addGestureRecognizer(customTap)
        }
        @objc private func handleCustomTap(_ sender: UITapGestureRecognizer) {
            let location = sender.location(in: self)
            guard let page = self.page(for: location, nearest: true) else { return }
            let pointOnPage = self.convert(location, to: page)
            if let annotation = page.annotation(at: pointOnPage) {
                // Trigger the custom action
                actionDelegate?.didTapAnnotation(annotation)
            }
        }
        // Intercept and block default PDFKit tap if an annotation is hit
        func gestureRecognizer(_ gestureRecognizer: UIGestureRecognizer, shouldReceive touch: UITouch) -> Bool {
            // We only want to block PDFKit's internal gestures, not our custom one
            guard gestureRecognizer is UITapGestureRecognizer, 
                  gestureRecognizer != self.gestureRecognizers?.first(where: { $0.action == #selector(handleCustomTap(_:)) }) else {
                return true
            }
            let location = touch.location(in: self)
            if let page = self.page(for: location, nearest: true) {
                let pointOnPage = self.convert(location, to: page)
                // If the touch lands on an annotation, block the default gesture
                if page.annotation(at: pointOnPage) != nil {
                    return false
                }
            }
            return true
        }
    }
    

    To integrate this with SwiftUI, we simply connected the `actionDelegate` within our `UIViewRepresentable`’s `makeUIView` function, routing the tapped annotation directly to a SwiftUI `@Binding` or `ObservableObject`. This completely suppressed the default edit menu without any visual flickering, allowing our custom drawer to open smoothly.

    What Can Engineering Teams Learn From This PDFKit Integration?

    Working around framework limitations requires architectural maturity. When organizations decide to hire software developer teams for complex product builds, they benefit from an engineering culture that understands these low-level mechanics. Here are the key takeaways:

    • Understand Responder Chains: When standard UI suppression techniques (like `hideMenu`) fail, the framework is likely bypassing the standard responder chain. Look toward gesture recognition layers instead.
    • Avoid UI Race Conditions: Never rely on hiding a UI element immediately after the framework tries to present it. The visual flicker degrades the premium feel of enterprise software. Prevent the presentation entirely.
    • Coordinate Spaces Matter: Converting touch points between the view coordinate space and the PDF page coordinate space (`self.convert(location, to: page)`) is critical for accurate hit testing in scalable document systems.
    • Respect the Framework Boundaries: By using standard `UIGestureRecognizerDelegate` methods to block touches, we avoided private APIs. This ensures the app remains stable during future iOS upgrades.
    • Leverage the Right Expertise: Deep framework integration can drastically slow down delivery if a team is unfamiliar with the underlying SDK. When you hire swift developers for mobile engineering, ensure they have proven experience with legacy and low-level Apple frameworks like PDFKit and CoreGraphics.

    How Do These Low-Level iOS Solutions Improve App Quality?

    Customizing the behavior of highly abstracted frameworks like PDFKit can be daunting, but it is often necessary to achieve a polished, brand-specific user experience. By intercepting gestures at the highest view level and performing custom hit-testing against the PDF document space, we successfully prevented the intrusive edit menu without compromising interactivity.

    If your organization is struggling with complex mobile architecture challenges or needs to scale an ongoing project with seasoned engineering talent, we can help. Feel free to contact us to learn how our dedicated teams ensure robust, scalable software delivery.

    Social Hashtags

    #SwiftUI #iOSDevelopment #PDFKit #SwiftProgramming #iOSDeveloper #PDFAnnotation #UIKit #MobileAppDevelopment #SwiftDevelopers #iOSAppDevelopment #AppleDeveloper #SoftwareEngineering

    Frequently Asked Questions

    Success Stories That Inspire

    See how our team takes complex business challenges and turns them into powerful, scalable digital solutions. From custom software and web applications to automation, integrations, and cloud-ready systems, each project reflects our commitment to innovation, performance, and long-term value.