eventkit

# EventKit

Use EventKit for calendar and reminder authorization, CRUD, recurrence, alarms,
and system editors.

## Contents

- [Availability](#availability)
- [Setup](#setup)
- [Authorization](#authorization)
- [Creating Events](#creating-events)
- [Fetching Events](#fetching-events)
- [Reminders](#reminders)
- [Recurrence Rules](#recurrence-rules)
- [Alarms](#alarms)
- [EventKitUI Controllers](#eventkitui-controllers)
- [Observing Changes](#observing-changes)
- [Common Mistakes](#common-mistakes)
- [Review Checklist](#review-checklist)
- [References](#references)

## Availability

- **iOS 17+:** Use granular full/write-only request methods; legacy
  `requestAccess(to:)` no longer prompts and throws. The system event editor can
  create an event without app calendar access. For iOS 10–16, guard those APIs,
  use the legacy request plus `NSCalendarsUsageDescription` /
  `NSRemindersUsageDescription`; EventKitUI may also need
  `NSContactsUsageDescription`.
- **iOS 26+:** The typed `EKEventStore.EventStoreChanged` / `.changed` message is
  available behind a guard. Keep `EKEventStoreChanged` for earlier systems.

## Setup

### Info.plist Keys

Add the usage description for the access path selected in
[Authorization](#authorization). Do not request broader access merely to simplify
the setup path.

The authorization-free system editor path needs no calendar usage string.
Direct writes need write-only or full access; reads need full access. Reminders
have only full access.

### Event Store

Create a single `EKEventStore` instance and reuse it. Do not mix objects from
different event stores.

```swift
import EventKit

let eventStore = EKEventStore()
```

## Authorization

Request the narrowest access that matches the feature. Apply the versioned
request path in [Availability](#availability).

| Key | Access Level |
|---|---|
| `NSCalendarsFullAccessUsageDescription` | Read + write events |
| `NSCalendarsWriteOnlyAccessUsageDescription` | Direct write-only event creation |
| `NSRemindersFullAccessUsageDescription` | Read + write reminders |

### Full Access to Events

Call `try await eventStore.requestFullAccessToEvents()` when the app needs to
read, edit, delete, or fetch calendar events.

### Write-Only Access to Events

Use when your app only creates events (e.g., saving a booking) and does not
need to read existing events.

Call `try await eventStore.requestWriteOnlyAccessToEvents()` before direct
EventKit writes that do not use `EKEventEditViewController`.

Write-only access can create events but cannot fetch calendars or events,
including app-created events. Use full access for later query, verification,
modification, or sync.

### Full Access to Reminders

Call `try await eventStore.requestFullAccessToReminders()` before reading,
creating, editing, or deleting reminders.

### Checking Authorization Status

Use `EKEventStore.authorizationStatus(for: .event)` or `.reminder` before work.
Handle `.notDetermined`, `.fullAccess`, `.writeOnly`, `.restricted`, `.denied`,
and `@unknown default`; only `.fullAccess` supports event/reminder reads.

## Creating Events

```swift
func createEvent(
    title: String,
    startDate: Date,
    endDate: Date,
    calendar: EKCalendar? = nil
) throws {
    let event = EKEvent(eventStore: eventStore)
    event.title = title
    event.startDate = startDate
    event.endDate = endDate
    event.calendar = calendar ?? eventStore.defaultCalendarForNewEvents

    try eventStore.save(event, span: .thisEvent)
}
```

### Setting a Specific Calendar

```swift
// List writable calendars
let calendars = eventStore.calendars(for: .event)
    .filter { $0.allowsContentModifications }

// Use the first writable calendar, or the default
let targetCalendar = calendars.first ?? eventStore.defaultCalendarForNewEvents
event.calendar = targetCalendar
```

### Adding Structured Location

```swift
import CoreLocation

let location = EKStructuredLocation(title: "Apple Park")
location.geoLocation = CLLocation(latitude: 37.3349, longitude: -122.0090)
event.structuredLocation = location
```

## Fetching Events

After the full-access gate in [Authorization](#authorization), use a date-range
predicate to query events. The `events(matching:)` method returns occurrences of
recurring events expanded within the range. Event predicates are capped to a
four-year span, and `events(matching:)` /
`enumerateEvents(matching:using:)` are synchronous and return only committed
events.

```swift
func fetchEvents(from start: Date, to end: Date) -> [EKEvent] {
    let predicate = eventStore.predicateForEvents(
        withStart: start,
        end: end,
        calendars: nil  // nil = all calendars
    )
    return eventStore.events(matching: predicate)
        .sorted { $0.startDate < $1.startDate }
}
```

### Fetching a Single Event by Identifier

```swift
if let event = eventStore.event(withIdentifier: savedEventID) {
    print(event.title ?? "No title")
}
```

## Reminders

### Creating a Reminder

```swift
func createReminder(title: String, dueDate: Date) throws {
    let reminder = EKReminder(eventStore: eventStore)
    reminder.title = title
    reminder.calendar = eventStore.defaultCalendarForNewReminders()

    let dueDateComponents = Calendar.current.dateComponents(
        [.year, .month, .day, .hour, .minute],
        from: dueDate
    )
    reminder.dueDateComponents = dueDateComponents

    try eventStore.save(reminder, commit: true)
}
```

### Fetching Reminders

Reminder fetches are asynchronous and return through a completion handler.

```swift
func fetchIncompleteReminders() async -> [EKReminder] {
    let predicate = eventStore.predicateForIncompleteReminders(
        withDueDateStarting: nil,
        ending: nil,
        calendars: nil
    )

    return await withCheckedContinuation { continuation in
        eventStore.fetchReminders(matching: predicate) { reminders in
            continuation.resume(returning: reminders ?? [])
        }
    }
}
```

### Completing a Reminder

`