How to return a rich view/custom view from AppEntity’s EntityQuery for Shortcuts app to display?

by

Summary

This postmortem analyzes why a custom AppEntity returned through EntityQuery in an AppIntent cannot produce the same rich, embedded Shortcuts UI that Apple’s Calendar app displays. The issue stems from framework limitations, not implementation mistakes. Apple’s own system apps use private, non‑public APIs to render rich inline views and detail sheets inside Shortcuts—capabilities that third‑party developers cannot currently replicate.

Root Cause

The root cause is simple but frustrating:

  • Shortcuts does not expose any public API for returning a rich, embedded view for an AppEntity.
  • System apps (Calendar, Reminders, Mail, etc.) use private frameworks to render their enhanced UI inside Shortcuts.
  • Snippet views only appear above Shortcuts, not inside the result list, because that is the only behavior Apple exposes publicly.
  • QuickLook previews are supported, but only for files or items conforming to Transferable, not arbitrary custom entities.

Why This Happens in Real Systems

This pattern is common in Apple’s ecosystem:

  • Apple apps often use private or privileged APIs unavailable to third‑party developers.
  • Public frameworks expose only a subset of the capabilities used internally.
  • Shortcuts is designed to keep third‑party integrations simple, predictable, and secure, limiting custom UI injection.
  • Rich UI inside Shortcuts requires tight OS‑level integration, which Apple restricts to system apps.

Real-World Impact

Developers attempting to match Calendar’s behavior encounter:

  • Inability to embed SwiftUI views inside Shortcuts results.
  • No way to show a tappable detail sheet for custom entities.
  • User experience inconsistency between system apps and third‑party apps.
  • Misleading expectations because Apple’s own apps demonstrate features that appear achievable but are not.

Example or Code (if necessary and relevant)

Below is a minimal AppEntity + EntityQuery implementation to illustrate the limitation.
This code works correctly but cannot produce embedded rich UI in Shortcuts.

struct TaskEntity: AppEntity {
    static var typeDisplayRepresentation = TypeDisplayRepresentation(name: "Task")

    var id: UUID
    var title: String

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(
            title: "\(title)"
        )
    }
}

struct TaskQuery: EntityQuery {
    func entities(for identifiers: [UUID]) async throws -> [TaskEntity] {
        // Fetch tasks
        return []
    }

    func suggestedEntities() async throws -> [TaskEntity] {
        // Provide suggestions
        return []
    }
}

This is the maximum UI Shortcuts will render for third‑party entities today.

How Senior Engineers Fix It

Experienced engineers recognize the limitation and design around it:

  • Use QuickLook previews when possible (only for file‑backed or transferable content).
  • Provide a Snippet view for richer UI, understanding it appears above Shortcuts, not embedded.
  • Offer deep links into the app for detail views.
  • Use AppIntents to return structured data, not UI, and let the app handle presentation.
  • Document the limitation so product teams understand it is a platform constraint, not an engineering failure.

Why Juniors Miss It

Less experienced developers often assume:

  • “If Calendar can do it, I should be able to do it too.”
  • “There must be a hidden API I’m not finding.”
  • “Snippet views should embed inside Shortcuts.”
  • “QuickLook should work for any entity.”

They miss the key insight: Shortcuts does not allow custom embedded UI for third‑party entities, and Apple has not documented any path to achieve it.

If you want, I can outline how to design a user flow that gracefully replaces the missing embedded UI.

Leave a Comment