{"id":15038651,"url":"https://github.com/mosheberman/mbcalendarkit","last_synced_at":"2025-04-04T11:13:30.609Z","repository":{"id":7959752,"uuid":"9357112","full_name":"MosheBerman/MBCalendarKit","owner":"MosheBerman","description":"An open source calendar framework for iOS, with support for customization, IBDesignable, Autolayout, and more.","archived":false,"fork":false,"pushed_at":"2019-09-29T03:01:45.000Z","size":34375,"stargazers_count":558,"open_issues_count":23,"forks_count":119,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-04-04T11:13:15.372Z","etag":null,"topics":["calendar","calendar-control","calendar-view","calendar-widget","ios","objective-c","swift","uikit"],"latest_commit_sha":null,"homepage":"","language":"Objective-C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MosheBerman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-04-10T22:12:43.000Z","updated_at":"2025-02-06T21:23:52.000Z","dependencies_parsed_at":"2022-08-21T04:20:18.947Z","dependency_job_id":null,"html_url":"https://github.com/MosheBerman/MBCalendarKit","commit_stats":null,"previous_names":[],"tags_count":33,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MosheBerman%2FMBCalendarKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MosheBerman%2FMBCalendarKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MosheBerman%2FMBCalendarKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MosheBerman%2FMBCalendarKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MosheBerman","download_url":"https://codeload.github.com/MosheBerman/MBCalendarKit/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247166168,"owners_count":20894654,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","calendar-control","calendar-view","calendar-widget","ios","objective-c","swift","uikit"],"created_at":"2024-09-24T20:39:30.276Z","updated_at":"2025-04-04T11:13:30.593Z","avatar_url":"https://github.com/MosheBerman.png","language":"Objective-C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Promo](https://github.com/MosheBerman/MBCalendarKit/raw/master/Promo/Banner.png)\n\n# About\n\nMBCalendarKit is a calendar control written in Objective-C with modern best practices and Swift interoperability in mind. \n\nIt offers a flexible calendar control, with support for displaying any calendar system supported by `NSCalendar`. It also includes an API to  customize the calendar cells. It also ships with a prebuilt view controller, inspired by the original iOS calendar. \n\n[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![Build Status](https://travis-ci.com/MosheBerman/MBCalendarKit.svg?branch=master)](https://travis-ci.com/MosheBerman/MBCalendarKit)\n\n## Features\n- Interactive Calendar Control\n- Autolayout Support\n- Dynamic Framework for iOS 8+\n- Custom Cell API with Default Implementation\n- Calendar Event Display\n- Custom First Weekday\n- Clamp Dates to Minimum and/or Maximum Values\n- Display for Any Locale or Calendar Identifier\n- Display Modes: Month, Week, and Day\n- Localization Support, Including Right-to-Left and Date Formatting\n- Pre-built View Controller inspired by the original iOS Calendar App\n- Sample App With Various Demo Implementations\n\n\n# Getting Started:\n\nYou'll need to target iOS 8+. There are ~three~ four ways to integrate MBCalendarKit:\n\n1. Cocoapods: `pod 'MBCalendarKit', '~\u003e 5.0.0'`\n2. Carthage: `github MosheBerman/MBCalendarKit ~\u003e 5.2.0`    \n3. Drag this Xcode project in to your own, and add the framework as a dependency.\n4. If you really want to drag the raw source in, the framework code is in `MBCalendarKit/CalendarKit`.\n\nIf there are any problems, please head over to issue #48 and leave a comment. \n\n## Swift \u0026 Objective-C\nMBCalendarKit is written in Objective-C. To use MBCalendarKit with Swift, just link against and use `import MBCalendarKit`.  MBCalendarKit 5.0.0 includes a number of Swift enhancements. \n\nThe examples here are in Swift, for berevity. Note that when writing Objective-C, MBCalendarKit prefixes its classes and enums with `CK`. `CalendarView` in Swift is `CKCalendarView` in Objective-C, etc. \n\nFor specifics, check out the [Migration Guide](./MIGRATIONGUIDE.md).\n\n\n# Features \n## Presenting a Calendar\nYou have two choices for showing a calendar using MBCalendarKit. \n\n1. You can show an instance of `CKCalendarView`. Use this if you want to manually manage your view hierarchy or just want a calendar view without the events table view.\n\n\n```` swift\n\n/// Here's how you'd show a CalendarView from within a view controller.\n/// Import the framework, then it's just three easy steps.\n\nimport MBCalendarKit\n    \t\n// 1. Instantiate a CKCalendarView\nlet calendar = CalendarView()\n \t\t\n// 2. Present the calendar \nself.view.addSubview(calendar)\n\n// 3. Add positioning constraints:\nself.calendarView.translatesAutoresizingMaskIntoConstraints = false\ncalendarView.topAnchor.constraint(equalTo:self.topLayoutGuide.bottomAnchor).isActive = true\ncalendarView.centerXAnchor.constraint(equalTo:self.view.centerXAnchor).isActive = true\n\n````\n\n2. Your second option is to create an instance of `CalendarViewController`. Using a CKCalendarViewController gives you the added benefit of a \"today\" button and a segmented control in the toolbar, which allows you to select the display mode. In MBCalendarKit 5.0.0 and later, you also use `CalendarViewController` if you'd like an events table view.\n\n\n```` swift\n\n/// Here's how you'd show a CalendarViewController from \n/// within a view controller. It's just three easy steps, including the framework import.\n\t\t\n// 1. Import MBCalendarKit:\nimport MBCalendarKit\n    \t\n// 2. Instantiate a CalendarViewController\nlet calendar = CalendarViewController()\n \t\t\n// 3. Present the calendar \nself.present(calendar animated:true completion:nil)\n\t\t\n````\n\nWith both `CalenderView` and `CalendarViewController`, you can use the `dataSource` and `delegate` properties to display events, and get information about user interation.\n\n---\n***Note:*** In older versions of MBCalendarKit, `CKCalendarViewController` used to subclass `UINavigationViewController`, so it couldn't be installed inside of another navigation controller. In 5.0.0, this is no longer the case. If you wish to embed your calendar inside a `UINavigationViewController`, you must now install it on your own. See the [Migration Guide](./MIGRATIONGUIDE.md) for details.\n\n---\n\nIn MBCalendarKit 5.0.0, there's a new property on `CalendarView` called `customCellProvider`, which can be used to customize the display of the cells in a really powerful way. Keep reading to learn more about setting up events\n\n\n## Showing Events\nThe `CKCalendarDataSource` protocol defines a method, which supplies an array of `CKCalendarEvent` objects. The calendar view automatically shows an indicator in cells that represent dates that have events. \n\n```` swift\nfunc calendarView(_ calendarView: CalendarView, eventsFor date: Date) -\u003e [CalendarEvent]\n````\nIn your data source, implement this method and return the events matching the date being passed in.\n\nHere's an example of adding a few events to the calendar:\n\n```` swift\nfunc adEventsToCalendar() {\n  let title : NSString = NSLocalizedString(\"Add Swift Demo\", comment: \"\") as NSString\n    if let date : Date = NSDate(day: 9, month: 1, year: 2015) as Date?\n    {\n      let event : CalendarEvent = CalendarEvent(title: title as String, andDate: date, andInfo: nil)\n      self.data[date] = [event]\n    } \n\n    let title2 : NSString = NSLocalizedString(\"Release MBCalendarKit 5.0.0\", comment: \"\") as NSString\n    if let date2 : Date = NSDate(day: 15, month: 8, year: 2017) as Date?\n    {\n      let event2 : CalendarEvent = CalendarEvent(title: title2 as String, andDate: date2, andInfo: nil)\n      self.data[date2] = [event2]\n    }\n}\n````\n\nNow, implement the data source:\n    \n````swift\n//  MARK: - CalendarDataSource\n\noverride func calendarView(_ calendarView: CalendarView, eventsFor date: Date) -\u003e [CalendarEvent] \n{\n    let eventsForDate = self.data[date] ?? []\n \n    return eventsForDate\n}\n````\n\n**Note:** The dates used as keys must match the dates passed into the data source method exactly. One way to ensure this is to use the `NSCalendar`'s `isDate:equalToDate:toUnitGranularity:`, passing in the two dates and `.day` as the third argument, to create the dates you pass to your events.\n\nYou can also see this code in `CKDemoViewController.m` or `SwiftDemoViewController.swift` in the demo app.\n\t\t\n## Handling User Interaction\nThese methods, defined in the `CalendarViewDelegate` protocol, are called on the delegate when the used selects a date. A date is considered selected when either an arrow in the header is tapped, or when the user lifts their finger from a cell.\n\n```` swift\nfunc calendarView(_ calendarView: CalendarView, willSelect date: Date) \nfunc calendarView(_ calendarView: CalendarView, didSelect date: Date) \n````  \n\nThis method is called on the delegate when a row is selected in the events table. You can use to push a detail view, for example.\n\n```` swift\nfunc calendarView(_ calendarView: CalendarView, didSelect event: CalendarEvent) \n````   \n\n## Customizing Cells \nMBCalendarKit 5.0.0 brings a brand new way to customize cells, so that you can add your own data to the cells, or even do a completely design. By building on top of `UICollectionView`, MBCalendarKit provides a really simple API. First, you need to implement `CustomCellProviding` in your code. This is composed of two parts: First, telling MBCalendarKit which `UICollectionViewCell` subclass to use for the cells, and second, implementing a method callback which will be your opportunity to customize the cell based on its context.\n\nLet's look at an implementation based on the default implementation:\n\n```` Swift\n\n// Step 1. Formally adopt the `CustomCellProviding` protocol\nClass MyCustomCellProvider: NSObject, CustomCellProviding {\n\n    // Step 2. Inform the framework of your `UICollectionViewCell` subclass, so it knows to use it.\n    var customCellClass: AnyClass\n    {\n        return CKCalendarCell.self\n    }\n\n    // Step 3. Implement the custom cell delegate callback\n    func calendarView(_ calendarView: CalendarView, willDisplay cell: UICollectionViewCell, in context: CalendarCellContext) {\n\n        // It's reasonable to cast to whatever class is in `customCellClass`.\n        guard let cell = cell as? CustomCalendarCell else\n        {\n            return\n        }\n\n        // Customize the cell's contents and display here.\n    }\n}\n````\n\nNow, simply tell the calendar view that your object is providing custom cells:\n\n```` swift\n// 0. Assume an existing calendarView\n\n// 1. Instantiate your custom cell provider.\nlet myCustomCellProvider = MyCustomCellProviderClass()\n\n// 2. Assign the custom cell provider to the calendar view's customCellProvider.\ncalendarView.customCellProvider = myCustomCellProvider\n\n````\n\nThat's it. The demo app and the migration guide have more information. \n\n---\n***Note:*** Prior to MBCalendarKit, customization of the cell's appearance was limited to properties accessible via `UIAppearance.` Those `UIAppearance` methods are still available in MBCalendarKit 5.0.0.\n\n---\n\n### Calendar Cell Contexts:\n\nIf you want to know which date the cell represents, or what scope the cell is being displayed in, look at the context object. `CKCalendarCellContext` has a few interesting properties:\n\nTo see the date represented by the cell, use the `date` property.:\n\n```` swift\nvar date: Date\n````\n\nTo see if the cell represents today, is out of the month, or even out of range of the calendar's minimum and maximum dates, use the context's `identifier` property, which is one of several `CalendarCellContextIdentifier` values.\n\n```` swift\nvar identifier: CKCalendarCellContextIdentifier\n````\n\nThe context identifier is based on several other flags, also available on `CalendarCellContext`. Check out the CocoaDocs generated documentation, or the class header for more.\n    \n\n## Calendar Events\n`CalendarEvent` is a simple data structure class which holds a title, a date, and an info dictionary. The calendar view will display automatically display `CalendarEvent` objects as passed to it by its data sourcee. If you have custom information that you want to show in a detail view, you can attach it to the event's `info` property. \n\nAs of MBCalendarKit 2.1.0, there's a `color` property as well. Setting it will cause the cell to display a colored \"tag\" in the cell. This feature should be considered experimental for now.\n\n\n## Customizing the First Day of the Week:\nVersion 2.2.0 adds support for the `firstWeekday` property of NSCalendar. If the `currentCalendar` (or whichever you set) has some day other than Sunday set as the first day of the week, the calendar view will respect that.\n\n\t/// Instantiate a CalendarViewController or CalendarView.\n    let calendarViewController = CKCalendarViewController()\n\n\t/// Set the first day of the week to Monday.\n    calendarViewController.calendarView.firstWeekDay = 2\n    \n**About the firstWeekDay property:** Use integers 1-7 to set a weekday from Sunday through Saturday. `NSCalendar` doesn't say what happens if you use another number, so you're on your own if you do that.\n  \n\n\n## Animating Week Transitions\nAs of MBCalendarKit 5.0.0, `CalendarView` has a `animatesWeekTransitions` property which can be turned on to enable animated transitions in week mode.\n\n---\n\n# Addendum\n\n\n## Thanks\nDave DeLong, for being an invaluable reference. Thanks to the folks on the iOS Folks Slack team for guidance on nullability and input on working around floating point division precision.\n\nThank you to the various [contributors]() for patches and reporting issues.\n\n## Want to Contribute?\nLearn more about contributing [by clicking here](https://github.com/MosheBerman/MBCalendarKit/blob/master/.github/CONTRIBUTING.md).\n\n## Code Of Conduct\nMBCalendarKit adopts the Contributor Covenant Code of Conduct. [Read it here.](https://github.com/MosheBerman/MBCalendarKit/blob/master/.github/CODE_OF_CONDUCT.md)\n\n## License\nMBCalendarKit is hereby released under the MIT License. See [LICENSE](/LICENSE) for details.\n\n## Like This?\nIf you like MBCalendarKit, check out some of my other projects:\n\n- [MBPlacePickerController](https://github.com/MosheBerman/MBPlacePickerController), a one stop shop for all of your CoreLocation needs, including a fallback UI for offline location setup.\n- [MBTileParser](https://github.com/MosheBerman/MBTileParser), a cocos-2d compatible game engine written in UIKit.\n- [MBTimelineViewController](https://github.com/MosheBerman/MBTimelineViewController), a scrolling timeline based on UICollectionView.\n- [MBMenuController](https://github.com/MosheBerman/MBMenuController), a UIActionSheet clone with some nice effects.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmosheberman%2Fmbcalendarkit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmosheberman%2Fmbcalendarkit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmosheberman%2Fmbcalendarkit/lists"}