eventkit

What this skill does

# EventKit

Create, read, and manage calendar events and reminders. Covers authorization,
event and reminder CRUD, recurrence rules, alarms, and EventKitUI editors.
Targets Swift 6.3 / iOS 26+.

## Contents

- [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)

## Setup

### Info.plist Keys

Add the required usage description strings based on what access level you need:

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

On iOS 17+, an app that only presents `EKEventEditViewController` to let the
person create an event does not need calendar authorization or calendar usage
strings. Direct EventKit writes need write-only or full calendar access; any
event read/fetch needs full calendar access. Reminders have only full access.

> For apps also running on iOS 10 through iOS 16, include the legacy
> `NSCalendarsUsageDescription` / `NSRemindersUsageDescription` keys. If using
> EventKitUI on those systems, also include `NSContactsUsageDescription` when the
> UI may need contact display names or avatars.

### 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

iOS 17+ introduced granular access levels. Request the narrowest access that
matches the feature. If the deployment target includes earlier OS versions,
availability-guard the iOS 17+ methods and fall back to `requestAccess(to:)`
only before iOS 17.

### 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`.

With write-only access, EventKit can create events but cannot read calendars or
events, including events the app created. Calendar reads return a virtual
calendar and event fetches return no events.

Use full access instead of write-only if the app must later query, verify,
modify, or sync saved events.

### 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

Use a date-range predicate to query events. The `events(matching:)` method
returns occurrences of recurring events expanded within the range. Fetching
events requires full calendar access; write-only access returns no events.
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

```swift
func completeReminder(_ reminder: EKReminder) throws {
    reminder.isCompleted = true
    try eventStore.save(reminder, commit: true)
}
```

## Recurrence Rules

Use `EKRecurrenceRule` to create repeating events or reminders.

### Simple Recurrence

```swift
// Every week, indefinitely
let weeklyRule = EKRecurrenceRule(
    recurrenceWith: .weekly,
    interval: 1,
    end: nil
)
event.addRecurrenceRule(weeklyRule)

// Every 2 weeks, ending after 10 occurrences
let biweeklyRule = EKRecurrenceRule(
    recurrenceWith: .weekly,
    interval: 2,
    end: EKRecurrenceEnd(occurrenceCount: 10)
)

// Monthly, ending on a specific date
let monthlyRule = EKRecurrenceRule(
    recurrenceWith: .monthly,
    interval: 1,
    end: EKRecurrenceEnd(end: endDate)
)
```

### Complex Recurrence

```swift
// Every Monday and Wednesday
let days = [
    EKRecurrenceDayOfWeek(.monday),
    EKRecurrenceDayOfWeek(.wednesday)
]

let complexRule = EKRecurrenceRule(
    recurrenceWith: .weekly,
    interval: 1,
    daysOfTheWeek: days,
    daysOfTheMonth: nil,
    monthsOfTheYear: nil,
    weeksOfTheYear: nil,
    daysOfTheYear: nil,
    setPositions: nil,
    end: nil
)
event.addRecurrenceRule(complexRule)
```

### Editing Recurring Events

When saving changes to a recurring event, specify the span:

```swift
// Change only this occurrence
try eventStore.save(event, span: .thisEvent)

// Change this and all future occurrences
try eventStore.save(event, span: .futureEvents)
```

## Alarms

Attach alarms to events or reminders to trigger notifications.

```swift
// 15 minutes before
let alarm = EKAlarm(relativeOffset: -15 * 60)
event.addAlarm(alarm)

// At an absolute date
let absoluteAlarm = EKAlarm(absoluteDate: alertDate)
event.addAlarm(absoluteAlarm)
```

For reminder geofences, put an `EKStructuredLocation` and `.enter` / `.leave`
proximity on an `EKAlarm`, then add it to