App Intents (iOS 26+)

Implement, review, and extend App Intents to expose app functionality to Siri, Shortcuts, Spotlight, widgets, Control Center, and Apple Intelligence.

Contents

• Triage Workflow
• AppIntent Protocol
• @Parameter
• AppEntity
• EntityQuery (4 Variants)
• AppEnum
• AppShortcutsProvider
• Siri Integration
• Interactive Widget Intents
• Control Center Widgets (iOS 18+)
• Spotlight and IndexedEntity (iOS 18+)
• iOS 26 Additions
• Common Mistakes
• Review Checklist
• References

Triage Workflow

Step 1: Identify the integration surface

Determine which system feature the intent targets:

Step 2: Define the data model

• Create AppEntity shadow models (do NOT conform core data models directly).
• Create AppEnum types for fixed parameter choices.
• Choose the right EntityQuery variant for resolution.
• Mark searchable entities with IndexedEntity and @Property(indexingKey:).

Step 3: Implement the intent

• Conform to AppIntent (or a specialized sub-protocol).
• Declare @Parameter properties for all user-facing inputs.
• Implement perform() async throws -> some IntentResult.
• Add parameterSummary for Shortcuts UI.
• Register phrases via AppShortcutsProvider.

Step 4: Verify

• Build and run in Shortcuts app to confirm parameter resolution.
• Test Siri phrases with the intent preview in Xcode.
• Confirm Spotlight results for IndexedEntity types.
• Check widget configuration for WidgetConfigurationIntent intents.

AppIntent Protocol

The system instantiates the struct via init(), sets parameters, then calls perform(). Declare a title and parameterSummary for Shortcuts UI.

struct OrderSoupIntent: AppIntent {
    static var title: LocalizedStringResource = "Order Soup"
    static var description = IntentDescription("Place a soup order.")

    @Parameter(title: "Soup") var soup: SoupEntity
    @Parameter(title: "Quantity", default: 1) var quantity: Int

    static var parameterSummary: some ParameterSummary {
        Summary("Order \(\.$soup)") { \.$quantity }
    }

    func perform() async throws -> some IntentResult {
        try await OrderService.shared.place(soup: soup.id, quantity: quantity)
        return .result(dialog: "Ordered \(quantity) \(soup.name).")
    }
}

Optional members: description (IntentDescription), openAppWhenRun (Bool), isDiscoverable (Bool), authenticationPolicy (IntentAuthenticationPolicy).

@Parameter

Declare each user-facing input with @Parameter. Optional parameters are not required; non-optional parameters with a default are pre-filled.

// WRONG: Non-optional parameter without default -- system cannot preview
@Parameter(title: "Count")
var count: Int

// CORRECT: Provide a default or make optional
@Parameter(title: "Count", default: 1)
var count: Int

@Parameter(title: "Count")
var count: Int?

Supported value types

Primitives: Int, Double, Bool, String, URL, Date, DateComponents. Framework: Currency, Person, IntentFile. Measurements: Measurement<UnitLength>, Measurement<UnitTemperature>, and others. Custom: any AppEntity or AppEnum.

Common initializer patterns

// Basic
@Parameter(title: "Name")
var name: String

// With default
@Parameter(title: "Count", default: 5)
var count: Int

// Numeric slider
@Parameter(title: "Volume", controlStyle: .slider, inclusiveRange: (0, 100))
var volume: Int

// Options provider (dynamic list)
@Parameter(title: "Category", optionsProvider: CategoryOptionsProvider())
var category: Category

// File with content types
@Parameter(title: "Document", supportedContentTypes: [.pdf, .plainText])
var document: IntentFile

// Measurement with unit
@Parameter(title: "Distance", defaultUnit: .miles, supportsNegativeNumbers: false)
var distance: Measurement<UnitLength>

See references/appintents-advanced.md for all initializer variants.

AppEntity

Create shadow models that mirror app data -- never conform core data model types directly.

struct SoupEntity: AppEntity {
    static let defaultQuery = SoupEntityQuery()
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Soup"
    var id: String

    @Property(title: "Name") var name: String
    @Property(title: "Price") var price: Double

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)", subtitle: "$\(String(format: "%.2f", price))")
    }

    init(from soup: Soup) {
        self.id = soup.id; self.name = soup.name; self.price = soup.price
    }
}

Required: id, defaultQuery (static), displayRepresentation, typeDisplayRepresentation (static). Mark properties with @Property(title:) to expose for filtering/sorting. Properties without @Property remain internal.

EntityQuery (4 Variants)

1. EntityQuery (base -- resolve by ID)

struct SoupEntityQuery: EntityQuery {
    func entities(for identifiers: [String]) async throws -> [SoupEntity] {
        SoupStore