Guide · Open source
How to use FSCalendar: install and add a calendar to iOS apps
Updated · written with AI from the project's own documentation and checked against our catalogue data
FSCalendar is an open-source iOS calendar library, licensed under MIT, that lets developers add a calendar view to an app instead of building one from scratch. It works with both Objective-C and Swift projects. This guide shows how to install it, add it in Interface Builder or in code, and handle the layout change that the library does not manage on its own.
FSCalendarWenchaoD/FSCalendar · ★ 10.6k · MIT Install options & downloads Quick start
- 1Pick an install route. Choose CocoaPods, Carthage, Swift Package Manager or a manual copy of the FSCalendar folder.
- 2Add the dependency. Add pod 'FSCalendar' to your Podfile, the Carthage github line to your Cartfile, or the Swift Package Manager dependency to your project.
- 3Add the calendar view. Place a UIView set to the FSCalendar class in Interface Builder, or create an FSCalendar instance in code and add it to your view.
- 4Set the data source and delegate. Assign dataSource and delegate on the calendar, then implement FSCalendarDataSource and FSCalendarDelegate in your view controller.
- 5Handle height changes. Implement boundingRectWillChange and update your height constraint or frame, since the library does not resize itself.
- 6Run the example. Open Example-Objc or Example-Swift in Xcode and run the UITest target to see the library in action.
What FSCalendar is and who it is for
FSCalendar is a code library, not a finished app. It gives iOS developers a calendar widget that users can view or pick dates from inside their own app. The library can be styled and customized, and the README says it works with both Objective-C and Swift projects.
It is a good fit for iOS developers who need a calendar or date-picker view, teams with existing Objective-C code that also want Swift support, and developers who want to customize the look and cell content. It is not meant for non-developers, and the README only describes iOS usage, so it is not a route for Android or web projects.
Install FSCalendar with CocoaPods, Carthage or Swift Package Manager
Choose the install route that matches your project. The README lists CocoaPods, Carthage, Swift Package Manager and a manual copy of files. Use Xcode with whichever tool you pick.
For CocoaPods, add the pod to your Podfile inside your target. The README notes that iOS 8+ setups use use_frameworks!, while iOS 7 support requires the separate NSCalendarExtension project.
For Swift Package Manager, add the package dependency shown below. For Carthage, add the line to your Cartfile.
- CocoaPods: add the pod inside your target block in the Podfile.
- Carthage: add the GitHub line to your Cartfile.
- Swift Package Manager: add the dependency in Xcode or Package.swift.
- Manual: drag all files under the FSCalendar folder into your project.
use_frameworks!
target '<Your Target Name>' do
pod 'FSCalendar'
endAdd the calendar in Interface Builder or in code
In Interface Builder, drag a UIView onto your view controller scene, change its Custom Class to FSCalendar, and link the dataSource and delegate outlets to your view controller. Then implement FSCalendarDataSource and FSCalendarDelegate in that controller. The README notes that only the CocoaPods iOS8+ and Carthage iOS8+ methods support IBInspectable and IBDesignable.
To add it in code, create the calendar in loadView or viewDidLoad, set its dataSource and delegate, and add it as a subview. The Objective-C example uses a frame of 320 by 300 points. For Swift, the README says you need to create a bridge header first when mixing languages.
- Interface Builder: UIView, Custom Class set to FSCalendar, dataSource and delegate linked.
- Code: initialize with a frame, set dataSource and delegate, add to the view, keep a weak reference.
let calendar = FSCalendar(frame: CGRect(x: 0, y: 0, width: 320, height: 300))
calendar.dataSource = self
calendar.delegate = self
view.addSubview(calendar)
self.calendar = calendarHandle calendar height changes in your layout
FSCalendar does not update its own frame. The README is explicit that your app must implement the boundingRectWillChange delegate method and resize the calendar. This matters because the calendar's height can change, for example when switching between month and week scope.
Use the example that matches your layout approach. The README gives examples for AutoLayout, manual layout, Masonry and SnapKit. Each one sets the calendar's height to the bounds passed in the callback.
- AutoLayout: set a height constraint's constant to the bounds height.
- Manual layout: set the calendar frame size to the bounds size.
- Masonry or SnapKit: update the height constraint, then call layoutIfNeeded.
- (void)calendar:(FSCalendar *)calendar boundingRectWillChange:(CGRect)bounds animated:(BOOL)animated
{
self.calendarHeightConstraint.constant = CGRectGetHeight(bounds);
[self.view layoutIfNeeded];
}Work with dates in Objective-C
The README's Pre-knowledge section covers basic date handling with NSCalendar and NSDateFormatter, which FSCalendar relies on. You can create a date from components or from a string with a format such as yyyy-MM-dd, and you can read components like year, month and day from a date.
In Swift 3 and later, the README says NSDate and NSDateFormatter were renamed to Date and DateFormatter, and it points to the Example-Swift project for details.
- Create a date from a string with NSDateFormatter and a yyyy-MM-dd format.
- Read individual parts such as year, month and day with NSCalendar.
self.formatter = [[NSDateFormatter alloc] init];
self.formatter.dateFormat = @"yyyy-MM-dd";
NSDate *date = [self.formatter dateFromString:@"2016-09-10"];Try the example projects
The README suggests a quick test run. Open the Example-Objc or Example-Swift project in Xcode and press command+u to run the UITest target. The README also points to DIY examples in these projects for custom cell content.
The README links to a wiki gallery with more screenshots and examples. Its screenshots cover iPhone, iPad, orientation handling, a Today extension, interactive scope gestures and swipe-to-choose selection.
- Open Example-Objc or Example-Swift and press command+u.
- Look in the example projects for custom cell (DIY) code.
What people use it for
- Adding a date picker view to an iOS app that lets users choose a date.
- Showing a month or week calendar where users view events on each day.
- Customizing the look of calendar cells with your own content, as shown in the DIY examples.
- Adding a calendar to an existing Objective-C app that is moving toward Swift.
Frequently asked questions
Is FSCalendar free to use?
FSCalendar is released under the MIT licence, according to the repository details. The README itself does not describe pricing, so check the licence file in the repository for the full terms.
How do I install FSCalendar?
You can install it with CocoaPods by adding pod 'FSCalendar' to your Podfile, with Carthage by adding github "WenchaoD/FSCalendar" to your Cartfile, or with Swift Package Manager using the package URL from the README. A manual install is also possible by dragging the FSCalendar folder files into your project.
Does FSCalendar work with Swift?
Yes. The README says FSCalendar is compatible with both Objective-C and Swift. For Swift projects that mix in Objective-C, you need to create a bridge header first.
Why doesn't my FSCalendar resize when the month changes?
The README states that FSCalendar does not update its frame by itself. You need to implement the boundingRectWillChange delegate method and update your height constraint or frame to the bounds it passes.
What platforms does FSCalendar support?
The README describes iOS usage only. The badges mention iOS 7+, and the README notes that iOS 7 needs the separate NSCalendarExtension dependency. It does not describe Android or web support.
What are alternatives to FSCalendar?
The source lists JTAppleCalendar and CVCalendar as comparable projects. Compare them on the features you need, such as customization and Swift support, by reading their own documentation.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
FSCalendar suits iOS developers who need a customizable calendar view and can handle layout updates in code. It is not a good choice for non-developers, Android or web projects, or teams that want the calendar to resize itself with no extra code.
Install options & downloads