CalendarViewRepresentable is the SwiftUI view type that represents the calendar. Like other SwiftUI views, all customization is done through initializer parameters and modifiers. To create a basic calendar, you initialize a CalendarViewRepresentable with some initial data:

let calendar = Calendar.current

let startDate = calendar.date(from: DateComponents(year: 2020, month: 01, day: 01))!
let endDate = calendar.date(from: DateComponents(year: 2021, month: 12, day: 31))!

CalendarViewRepresentable(
  calendar: calendar,
  visibleDateRange: startDate...endDate,
  monthsLayout: .vertical(options: VerticalMonthsLayoutOptions()),
  dataDependency: nil)

CalendarView is the UIView subclass that renders the calendar. All visual aspects of CalendarView are controlled through a single type - CalendarViewContent. To create a basic CalendarView, you initialize one with an initial CalendarViewContent:

let calendarView = CalendarView(initialContent: makeContent())

private func makeContent() -> CalendarViewContent {
  let calendar = Calendar.current

  let startDate = calendar.date(from: DateComponents(year: 2020, month: 01, day: 01))!
  let endDate = calendar.date(from: DateComponents(year: 2021, month: 12, day: 31))!

  return CalendarViewContent(
    calendar: calendar,
    visibleDateRange: startDate...endDate,
    monthsLayout: .vertical(options: VerticalMonthsLayoutOptions()))
}

At a minimum, CalendarViewContent must be initialized with a Calendar, a visible date range, and a months layout (either vertical or horizontal). The visible date range will be interpreted as a range of days using the Calendar instance passed in for the calendar parameter.

For this example, we’re using a Gregorian calendar, a date range of 2020-01-01 to 2021-12-31, and a vertical months layout.

Make sure to add calendarView as a subview, then give it a valid frame either using Auto Layout or by manually setting its frame property. If you’re using Auto Layout, note that CalendarView does not have an intrinsic content size.

view.addSubview(calendarView)

calendarView.translatesAutoresizingMaskIntoConstraints = false

NSLayoutConstraint.activate([
  calendarView.leadingAnchor.constraint(equalTo: view.layoutMarginsGuide.leadingAnchor),
  calendarView.trailingAnchor.constraint(equalTo: view.layoutMarginsGuide.trailingAnchor),
  calendarView.topAnchor.constraint(equalTo: view.layoutMarginsGuide.topAnchor),
  calendarView.bottomAnchor.constraint(equalTo: view.layoutMarginsGuide.bottomAnchor),
])

Add your calendar to the view hierarchy like any other SwiftUI view. Since the calendar doesn’t have an intrinsic content size, you’ll need to use the frame modifier to tell SwiftUI that it should consume all vertical and horizontal space. Optionally, use the layoutMargins modifier to apply internal padding, and the normal SwiftUI padding modifier to apply some external padding from the parent’s edges.

var body: some View {
  CalendarViewRepresentable(...)
    .layoutMargins(.init(top: 8, leading: 8, bottom: 8, trailing: 8))
    .padding(.horizontal, 16)
    .frame(maxWidth: .infinity, maxHeight: .infinity)
}

Add your calendar as a subview, then give it a valid frame either using Auto Layout or by manually setting its frame property. If you’re using Auto Layout, note that CalendarView does not have an intrinsic content size.

view.addSubview(calendarView)

calendarView.translatesAutoresizingMaskIntoConstraints = false

NSLayoutConstraint.activate([
  calendarView.leadingAnchor.constraint(equalTo: view.layoutMarginsGuide.leadingAnchor),
  calendarView.trailingAnchor.constraint(equalTo: view.layoutMarginsGuide.trailingAnchor),
  calendarView.topAnchor.constraint(equalTo: view.layoutMarginsGuide.topAnchor),
  calendarView.bottomAnchor.constraint(equalTo: view.layoutMarginsGuide.bottomAnchor),
])

Since all visual aspects of CalendarViewRepresentable are configured through modifiers, we’ll use the days modifier to provide a custom view with a rounded border for each day in the calendar:

CalendarViewRepresentable(...)

  .days { day in
    Text("\(day.day)")
      .font(.system(size: 18))
      .foregroundColor(Color(UIColor.label))
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .overlay {
        RoundedRectangle(cornerRadius: 12)
          .stroke(Color(UIColor.systemBlue), lineWidth: 1)
      }
  }

To use a UIKit view, wrap it using UIViewRepresentable and return it from the same function.

Note

View-provider closures are invoked lazily as parts of the calendar come into view. If you read any view state in any of your view-provider closures, make sure you capture it explicitly using a capture list. If you don’t, SwiftUI will fail to identify that state as a dependency of your view unless it was read during the initial body evaluation of your view. This will lead to missed updates when your state changes.

Since all visual aspects of CalendarView are configured through CalendarViewContent, we’ll expand on our makeContent function. Let’s start by providing a custom view for each day in the calendar:

private func makeContent() -> CalendarViewContent {
  return CalendarViewContent(...)
    .dayItemProvider { day in
      // Return a `CalendarItemModel` representing the view for each day
    }
}

The dayItemProvider(_:) function on CalendarViewContent returns a new CalendarViewContent instance with the custom day item model provider configured. This function takes a single parameter - a provider closure that returns a CalendarItemModel for a given DayComponents.

CalendarItemModel is a type that abstracts away the creation and configuration of a view displayed in the calendar. It’s generic over a ViewRepresentable type, which can be any type conforming to CalendarItemViewRepresentable. You can think of CalendarItemViewRepresentable as a blueprint for creating and updating instances of a particular type of view to be displayed in the calendar. For example, if we want to use a UILabel for our custom day view with a rounded border, we’ll need to create a type that knows how to create and update that label. Here’s a simple example:

import HorizonCalendar

struct DayLabel: CalendarItemViewRepresentable {

  /// Properties that are set once when we initialize the view.
  struct InvariantViewProperties: Hashable {
    let font: UIFont
    let textColor: UIColor
    let borderColor: UIColor
  }

  /// Properties that will vary depending on the particular date being displayed.
  struct Content: Equatable {
    let day: DayComponents
  }

  static func makeView(
    withInvariantViewProperties invariantViewProperties: InvariantViewProperties)
    -> UILabel
  {
    let label = UILabel()
    
    label.isUserInteractionEnabled = true
    label.layer.borderWidth = 1
    label.layer.borderColor = invariantViewProperties.borderColor.cgColor
    label.font = invariantViewProperties.font
    label.textColor = invariantViewProperties.textColor

    label.textAlignment = .center
    label.clipsToBounds = true
    label.layer.cornerRadius = 12
    
    return label
  }

  static func setContent(_ content: Content, on view: UILabel) {
    view.text = "\(content.day.day)"
  }

}

CalendarItemViewRepresentable requires us to implement a static makeView function, which should create and return a view given a set of invariant view properties. We want our label to have a configurable font and text color, so we’ve made those configurable via the InvariantViewProperties type. In our makeView function, we use those invariant view properties to create and configure an instance of our label.

CalendarItemViewRepresentable also requires us to implement a static setContent function, which should update all data-dependent properties (like the day text) on the provided view.

Now that we have a type conforming to CalendarItemViewRepresentable, we can use it to create a CalendarItemModel to return from the day item model provider:

return CalendarViewContent(...)

  .dayItemProvider { day in
    DayLabel.calendarItemModel(
      invariantViewProperties: .init(
        font: .systemFont(ofSize: 18), 
        textColor: .label,
        borderColor: .systemBlue),
      content: .init(day: day))
  }

Using a SwiftUI view is even easier - simply initialize your SwiftUI view and call .calendarItemModel on it. There’s no need to create a custom type conforming to CalendarItemViewRepresentable like we had to do with the UIKit example above, or have separate concepts for invariant and variant (content) view properties.

return CalendarViewContent(...)

  .dayItemProvider { day in
    Text("\(day.day)")
      .font(.system(size: 18))
      .foregroundColor(Color(UIColor.label))
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .overlay {
        RoundedRectangle(cornerRadius: 12)
          .stroke(Color(UIColor.systemBlue), lineWidth: 1)
      }
      .calendarItemModel
  }

CalendarViewRepresentable(...)
  .days { ... }

  .interMonthSpacing(24)
  .verticalDayMargin(8)
  .horizontalDayMargin(8)

return CalendarViewContent(...)
  .dayItemProvider { ... }

  .interMonthSpacing(24)
  .verticalDayMargin(8)
  .horizontalDayMargin(8)

Just like when we configured a custom day view via the day provider, changes to layout metrics are also done through CalendarViewContent. interMonthSpacing(_:), verticalDayMargin(_:), and horizontalDayMargin(_:) each return a mutated CalendarViewContent with the corresponding layout metric value updated, enabling you to chain function calls together to produce a final content instance.

Next, we’ll use the dayRanges modifier on our CalendarViewRepresentable:

CalendarViewRepresentable(...)
  ...
  
  .dayRanges(for: [dateRangeToHighlight]) { dayRangeLayoutContext in 
    DayRangeIndicatorViewRepresentable(
      framesOfDaysToHighlight: dayRangeLayoutContext.daysAndFrames.map { $0.frame })
  }

For each day range derived from the Set<ClosedRange<Date>> passed into this modifier, our day range provider closure will be invoked with a context instance that contains all of the information needed for us to create a view to be used to highlight a particular day range. Since DayRangeIndicatorView is a UIView, we need to bridge it to SwiftUI using UIViewRepresentable:

struct DayRangeIndicatorViewRepresentable: UIViewRepresentable {

  let framesOfDaysToHighlight: [CGRect]

  func makeUIView(context: Context) -> DayRangeIndicatorView {
    DayRangeIndicatorView(indicatorColor: UIColor.systemBlue.withAlphaComponent(0.15))
  }

  func updateUIView(_ uiView: DayRangeIndicatorView, context: Context) {
    uiView.framesOfDaysToHighlight = framesOfDaysToHighlight
  }

}

Note

When wrapping a UIKit view in a UIViewRepresentable, there is no equivalent concept of invariant view properties; all customizable properties must be updated in updateUIView to prevent view-reuse issues.

Next, we need to invoke the dayRangeItemProvider(for:_:) on our CalendarViewContent:

  return CalendarViewContent(...)
    ...
    
    .dayRangeItemProvider(for: [dateRangeToHighlight]) { dayRangeLayoutContext in 
      // Return a `CalendarItemModel` representing the view that highlights the entire day range
    }

For each day range derived from the Set<ClosedRange<Date>> passed into this function, our day range item model provider closure will be invoked with a context instance that contains all of the information needed for us to render a view to be used to highlight a particular day range. Here is an example implementation of such a view:

Next, we need a type that conforms to CalendarItemViewRepresentable that knows how to create and update instances of DayRangeIndicatorView. To make things easy, we can just make our view conform to this protocol:

import HorizonCalendar

extension DayRangeIndicatorView: CalendarItemViewRepresentable {

  struct InvariantViewProperties: Hashable {
    let indicatorColor: UIColor
  }

  struct Content: Equatable {
    let framesOfDaysToHighlight: [CGRect]
  }

  static func makeView(
    withInvariantViewProperties invariantViewProperties: InvariantViewProperties)
    -> DayRangeIndicatorView
  {
    DayRangeIndicatorView(indicatorColor: invariantViewProperties.indicatorColor)
  }

  static func setContent(_ content: Content, on view: DayRangeIndicatorView) {
    view.framesOfDaysToHighlight = content.framesOfDaysToHighlight
  }

}

Last, we need to return a CalendarItemModel representing our DayRangeIndicatorView from the day range item model provider closure:

  return CalendarViewContent(...)
    ...
    
    .dayRangeItemProvider(for: [dateRangeToHighlight]) { dayRangeLayoutContext in
      DayRangeIndicatorView.calendarItemModel(
        invariantViewProperties: .init(indicatorColor: UIColor.blue.withAlphaComponent(0.15)),
        content: .init(framesOfDaysToHighlight: dayRangeLayoutContext.daysAndFrames.map { $0.frame }))
    }

CalendarViewRepresentable(...)

  .monthBackgrounds { monthLayoutContext in
    MonthGridBackgroundViewRepresentable(
      framesOfDays: monthLayoutContext.daysAndFrames.map { $0.frame })
  }

Since MonthGridBackgroundView is a UIView, we need to bridge it to SwiftUI using UIViewRepresentable:

struct MonthGridBackgroundViewRepresentable: UIViewRepresentable {

  let framesOfDays: [CGRect]

  func makeUIView(context: Context) -> MonthGridBackgroundView {
    MonthGridBackgroundView(
      invariantViewProperties: .init(horizontalDayMargin: 8, verticalDayMargin: 8))
  }

  func updateUIView(_ uiView: MonthGridBackgroundView, context: Context) {
    uiView.framesOfDays = framesOfDays
  }

}

Note

When wrapping a UIKit view in a UIViewRepresentable, there is no equivalent concept of invariant view properties; all customizable properties must be updated in updateUIView to prevent view-reuse issues.

return CalendarViewContent(...)
  
  .monthBackgroundItemProvider { monthLayoutContext in
    MonthGridBackgroundView.calendarItemModel(
      invariantViewProperties: .init(horizontalDayMargin: 8, verticalDayMargin: 8),
      content: .init(framesOfDays: monthLayoutContext.daysAndFrames.map { $0.frame }))
  }

In SwiftUI, responding to day selection is easy.

First, define a state property for the current selected date:

@State var selectedDate: Date?

Then, update the selected date using the onDaySelection modifier:

CalendarViewRepresentable(...)
  ...
  
  .onDaySelection { day in
    selectedDate = calendar.date(from: day.components)
  }

Last, return a different view in your day provider closure:

CalendarViewRepresentable(...)
  ...
  
  .days { [selectedDate] day in
    let date = calendar.date(from: day.components)
    let borderColor: UIColor = date == selectedDate ? .systemRed : .systemBlue
    
    Text("\(day.day)")
      .font(.system(size: 18))
      .foregroundColor(Color(UIColor.label))
      .frame(maxWidth: .infinity, maxHeight: .infinity)
      .overlay {
        RoundedRectangle(cornerRadius: 12)
          .stroke(Color(borderColor), lineWidth: 1)
      }
  }

Note

View-provider closures are invoked lazily as parts of the calendar come into view. If you read any view state in any of your view-provider closures, make sure you capture it explicitly using a capture list. If you don’t, SwiftUI will fail to identify that state as a dependency of your view unless it was read during the initial body evaluation of your view. This will lead to missed updates when your state changes.

In UIKit, provide a day selection handler closure by setting CalendarView’s daySelectionHandler:

calendarView.daySelectionHandler = { [weak self] day in
  self?.selectedDate = calendar.date(from: day.components)
}

private var selectedDate: Date?

The day selection handler closure is invoked whenever a day in the calendar is selected. You’re provided with a DayComponents instance for the day that was selected. If we want to highlight the selected day once its been tapped, we’ll need to create a new CalendarViewContent with a day calendar item model that looks different for the selected day:

let selectedDay = self.selectedDay

return CalendarViewContent(...)
  ...

  .dayItemProvider { [selectedDate] day in
    let date = calendar.date(from: day.components)
    let borderColor: UIColor = date == selectedDate ? .systemRed : .systemBlue

    return DayLabel.calendarItemModel(
      invariantViewProperties: .init(
        font: .systemFont(ofSize: 18),
        textColor: .label,
        borderColor: borderColor),
      content: .init(day: day))
  }

Last, we’ll change our day selection handler so that it not only stores the selected date, but also sets an updated content instance on calendarView:

calendarView.daySelectionHandler = { [weak self] day in
  guard let self else { return }

  selectedDate = calendar.date(from: day.components)

  let newContent = makeContent()
  calendarView.setContent(newContent)
}