Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


Cocoapods CI codecov codebeat badge contributions

KNContacts is wrapper for CNContacts for easier access to information like current age and age at next birthday, full contact name, creating contact books (groups), ordering them and creating contact schedules.

More information

KNContacts framework features a couple of classes, structs and enums to facilitate access to contacts, contact books and schedule of contacts.

Type Name Description
struct KNContact Wrapper struct for CNContact, provides access to helper methods and original contact details.
class KNContactBook Collection of KNContacts with methods for adding, removing, sorting and retrieving specific or random elements
struct KNContactBookOrdering Helper ordering methods to sort contacts in KNContactBook
struct KNContactsSchedule Dictionary wrapper for creating contact schedule for using custom time formats for scheduling and retrieving at a particular time
struct KNDatesUtils Date formatting helper methods
enum KNTimeFormat Enum with pre-defined time formats


You can check the full documentation here.


Sample initialisation and usage

KNContact and KNContactBook

KNContact is a wrapper structure and you can initialise a new obejct by passing in a CNContact or CNMutableContact object. KNContactBook is a collection of KNContact objects which can be sorted and random elements extracted.

import Contacts
import KNContacts

var contactBook = KNContactBook(id: "allContacts")

// Retrieve or create your CNContact list from a store - KNContacts does *not* handle authorisation for you.
// Make sure you have all necessary key descriptors.

var keys = [CNContactGivenNameKey, CNContactMiddleNameKey, CNContactFamilyNameKey,
            CNContactEmailAddressesKey, CNContactBirthdayKey, CNContactPhoneNumbersKey,
            CNContactFormatter.descriptorForRequiredKeys(for: .fullName)] as! [CNKeyDescriptor]

let requestForContacts = CNContactFetchRequest(keysToFetch: keys)

do {
    try CNContactStore().enumerateContacts(with: requestForContacts) { (cnContact, _) in
        let knContact = KNContact(cnContact)
} catch let error {
    // Handle error somehow!

// And then perform actions on KNContactBook
let randomContacts = contactBook.randomElements(number: 1)
let randomElements = contactBook.randomElements(number: 3, except: randomContacts)

randomElements.forEach({ (contact) in 
    print(contact.fullName(format: .fullName))
    if (contact.isBirthdayToday()) {
        print("It's their birthday today!")
    } else if (contact.isBirthdayComing(in: 7)) {
        print("Birthday coming up in the next week!")
    } else {
        print("Birthday on \(contact.formatBirthday())")

KNContactsSchedule, KNContactBookOrdering, KNDatesUtils

KNContact can also return ordered array of elements. Two options are provided in KNContactBookOrdering But the toArray(orderedBy:) method can take any sorting function. KNDatesUtils provides easy access to string date formatters.

let order = KNContactBookOrdering.thisYearsBirthday
let contactsSortedByBirthday = contactBook.contacts.sorted(by: order)

// And finally schedules can be created for easier retrieval at a later date.
var thisWeeksBirthdaySchedule = KNContactsSchedule(name: "birthdaysThisYear")

for numberOfDays in 1...7 {
    let birthdayList = contactsSortedByBirthday.filter({ $0.isBirthdayComing(in: numberOfDays) }).map({ $ })
    let date = .day, value: numberOfDays, to: Date())!
    let dateString = KNDatesUtils.formatter(with: .fullDate).string(from: date)
    thisWeeksBirthdaySchedule.add(list: birthdayList, to: dateString)

// And retrieve schedule by date
let tomorrow = .day, value: 1, to: Date())!
let schedule = thisWeeksBirthdaySchedule.getSchedule(for: tomorrow)


KNContacts version Swift Version Package Managers Supported
from v1.3.0 Swift 5.0 Swift Package Manager, Cocoapods
from v1.2.0 Swift 5.0 Cocoapods
up to v1.1.1 Swift 4.2 Cocoapods


KNContacts is currently available using CocoaPods and Swift Package Manager. Just add this snippet into your podfile to use the latest version.


pod 'KNContacts'

or specify the desired version.

pod 'KNContacts', '~> 1.0.0'

Swift Package Manager

Once you have SPM set up, add this package to the dependencies. SPM has been supported only since version 1.3.0.

dependencies: [
    .package(url: "", .upToNextMajor(from: "1.3.0"))

Applications using KNContacts

If your app uses KNContacts, feel free to submit a Pull Request.


Pull requests are welcome, all changes should be accompanied by tests and a passing build.

Issues or features requests are welcome, feel free to create implementations yourself. The development of this framework is done using trunk based development strategy so please create your pull requests against the master branch and ensure the build is passing.


This library is MIT Licensed.